{"openapi":"3.1.0","info":{"title":"Conttrole — API de Integração","description":"API pública para emissão e consulta de documentos fiscais eletrônicos (NF-e, NFC-e, NFS-e). Autenticação por API Key por empresa. Veja docs/API_RAILWAY.md no repositório.","version":"1.0.0","contact":{"name":"Conttrole","url":"https://conttrole.io"},"x-logo":{"url":"https://docs.conttrole.io/logo-degrade.png","altText":"Conttrole"}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Chave de API da empresa. Header: 'Authorization: Bearer ck_live_...'."}},"schemas":{}},"paths":{"/health":{"get":{"summary":"Liveness — o processo está no ar","tags":["Health"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"uptime":{"type":"number","description":"Segundos desde o boot do processo"}},"required":["status","version","uptime"],"additionalProperties":false}}}}}}},"/health/ready":{"get":{"summary":"Readiness — dependências (banco) respondendo","tags":["Health"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"database":{"type":"string","enum":["up"]}},"required":["status","database"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"database":{"type":"string","enum":["down"]}},"required":["status","database"],"additionalProperties":false}}}}}}},"/v1/fiscal-documents":{"get":{"summary":"Lista documentos fiscais da empresa","tags":["Fiscal Documents"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false,"description":"Página (1-based)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"pageSize","required":false,"description":"Itens por página (máx. 100)"},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filtra por status (ex: AUTHORIZED, DRAFT)"},{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Filtra por tipo (NFE/NFCE/NFSE)"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"NFE | NFCE | NFSE"},"status":{"type":"string"},"series":{"type":"integer","nullable":true},"number":{"type":"integer"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"totalValue":{"type":"string","description":"Valor total (decimal como string)"},"issueDateTime":{"type":"string","description":"Data de emissão (ISO 8601)"},"authorizationDate":{"type":"string","nullable":true},"pdfUrl":{"type":"string","nullable":true},"xmlUrl":{"type":"string","nullable":true}},"required":["id","type","status","series","number","accessKey","totalValue","issueDateTime","authorizationDate","pdfUrl","xmlUrl"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um documento fiscal (rascunho)","tags":["Fiscal Documents"],"description":"Cria uma NF-e (modelo 55), NFC-e (modelo 65) ou NFS-e em DRAFT a partir de um cliente já cadastrado e dos itens informados. Os impostos podem vir explícitos no item, por uma regra tributária (`taxRuleId` no documento ou no item — ver GET /v1/tax-rules) ou, na ausência de ambos, pela configuração da empresa; NCM ausente herda o da empresa. Use `emit: true` para já disparar a emissão (assíncrona) — ou chame depois `POST /fiscal-documents/{id}/emit`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento"},"clientId":{"type":"string","description":"ID de um cliente já cadastrado nesta empresa"},"operationNature":{"type":"string","description":"Natureza da operação. Default: 'Venda de mercadoria'."},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Código/SKU do item"},"description":{"type":"string","description":"Descrição do item"},"ncm":{"type":"string","nullable":true,"description":"NCM (8 dígitos). Sem valor, herda o NCM da empresa (NF-e)."},"serviceCode":{"type":"string","nullable":true,"description":"Código de serviço municipal (NFS-e)"},"nationalServiceCode":{"type":"string","nullable":true,"description":"Código de serviço nacional (NFS-e)"},"cfop":{"type":"string","description":"CFOP (NF-e/NFC-e). Opcional para NFS-e."},"unit":{"type":"string","description":"Unidade comercial. Default: UN."},"quantity":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Quantidade"},"unitValue":{"type":"number","minimum":0,"description":"Valor unitário"},"icmsOrigin":{"type":"string","nullable":true},"icmsSituation":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS"},"icmsRate":{"type":"number","nullable":true},"pisSituation":{"type":"string","nullable":true},"pisRate":{"type":"number","nullable":true},"cofinsSituation":{"type":"string","nullable":true},"cofinsRate":{"type":"number","nullable":true},"ipiSituation":{"type":"string","nullable":true},"ipiRate":{"type":"number","nullable":true},"taxRuleId":{"type":"string","nullable":true,"description":"ID de uma regra tributária (GET /v1/tax-rules) a aplicar neste item. Sobrepõe o taxRuleId do documento. Os campos de imposto explícitos acima têm prioridade sobre a regra."}},"required":["code","description","quantity","unitValue"],"additionalProperties":false},"minItems":1,"description":"Itens do documento"},"payments":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["MONEY","CHECK","CREDIT_CARD","DEBIT_CARD","BANK_CREDIT","BANK_TRANSFER","BANK_SLIP","PIX","BANK_TRANSFER_TED","BANK_TRANSFER_DOC","NO_PAYMENT","OTHERS"],"description":"Forma de pagamento (enum). Ex: MONEY, PIX, CREDIT_CARD."},"value":{"type":"number","description":"Valor pago nesta forma"},"description":{"type":"string","nullable":true,"description":"Descrição da forma de pagamento. Obrigatória quando OTHERS."},"cardFlag":{"type":"string","enum":["AMERICAN_EXPRESS","DINERS_CLUB","DISCOVER","ELO","HIPERCARD","HIPER","JCB","MAESTRO","MASTERCARD","MIR","UNIONPAY","VISA","OTHER"],"nullable":true,"description":"Bandeira do cartão (cartão de crédito/débito)"},"cardCNPJ":{"type":"string","nullable":true,"description":"CNPJ da credenciadora/adquirente do cartão"},"cardAuthorization":{"type":"string","nullable":true,"description":"Código de autorização da operação com cartão"},"pixKey":{"type":"string","nullable":true,"description":"Chave PIX usada no recebimento"},"pixTxId":{"type":"string","nullable":true,"description":"TxId/identificador da transação PIX"}},"required":["method","value"],"additionalProperties":false}},"taxRuleId":{"type":"string","nullable":true,"description":"ID de uma regra tributária (GET /v1/tax-rules) aplicada a todos os itens sem taxRuleId próprio. Sem isso, usa a configuração tributária da empresa. Impostos enviados no item têm prioridade."},"additionalInfo":{"type":"string","nullable":true,"description":"Informações complementares"},"externalId":{"type":"string","nullable":true,"description":"ID externo da venda (para dedup/rastreio na sua ponta)"},"issueDateTime":{"type":"string","format":"date-time","description":"Data de emissão (ISO 8601). Default: agora."},"emit":{"type":"boolean","description":"Quando true, já enfileira a emissão (assíncrona) após criar o rascunho."}},"required":["type","clientId","items"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"NFE | NFCE | NFSE"},"status":{"type":"string"},"series":{"type":"integer","nullable":true},"number":{"type":"integer"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"totalValue":{"type":"string","description":"Valor total (decimal como string)"},"issueDateTime":{"type":"string","description":"Data de emissão (ISO 8601)"},"authorizationDate":{"type":"string","nullable":true},"pdfUrl":{"type":"string","nullable":true},"xmlUrl":{"type":"string","nullable":true},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev (presente quando emit=true)"}},"required":["id","type","status","series","number","accessKey","totalValue","issueDateTime","authorizationDate","pdfUrl","xmlUrl","runId"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/emit":{"post":{"summary":"Dispara a emissão de um documento fiscal (assíncrono)","tags":["Fiscal Documents"],"description":"Coloca o documento em PROCESSING e enfileira a emissão no Trigger.dev. Vale para NF-e (modelo 55), NFC-e (modelo 65) e NFS-e — o tipo é definido no próprio documento. NFC-e exige CSC configurado na empresa. Só documentos em DRAFT ou REJECTED podem ser emitidos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"issueDateTime":{"type":"string","format":"date-time","description":"Data de emissão (ISO 8601). Default: agora."}},"additionalProperties":false,"nullable":true}]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string"},"status":{"type":"string","enum":["PROCESSING"]},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev"},"message":{"type":"string"}},"required":["documentId","status","runId","message"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"429":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"503":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}":{"get":{"summary":"Detalha um documento fiscal pelo id","tags":["Fiscal Documents"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"NFE | NFCE | NFSE"},"status":{"type":"string"},"series":{"type":"integer","nullable":true},"number":{"type":"integer"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"totalValue":{"type":"string","description":"Valor total (decimal como string)"},"issueDateTime":{"type":"string","description":"Data de emissão (ISO 8601)"},"authorizationDate":{"type":"string","nullable":true},"pdfUrl":{"type":"string","nullable":true},"xmlUrl":{"type":"string","nullable":true},"nfseNumber":{"type":"string","nullable":true,"description":"Número oficial da NFS-e"},"verificationCode":{"type":"string","nullable":true,"description":"Código de verificação"},"protocolNumber":{"type":"string","nullable":true,"description":"Protocolo de autorização"},"rejectionReason":{"type":"string","nullable":true,"description":"Motivo da rejeição (quando status REJECTED)"},"cancellationReason":{"type":"string","nullable":true},"cancellationDate":{"type":"string","nullable":true}},"required":["id","type","status","series","number","accessKey","totalValue","issueDateTime","authorizationDate","pdfUrl","xmlUrl","nfseNumber","verificationCode","protocolNumber","rejectionReason","cancellationReason","cancellationDate"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/cancel":{"post":{"summary":"Cancela um documento fiscal autorizado","tags":["Fiscal Documents"],"description":"Cancela uma NF-e/NFC-e/NFS-e AUTORIZADA junto à SEFAZ/prefeitura (observando o prazo legal). Síncrono: aguarda o fisco e devolve o resultado. A justificativa deve ter 15–255 caracteres (regra SEFAZ).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"justification":{"type":"string","minLength":15,"maxLength":255,"description":"Justificativa do cancelamento (15–255 caracteres)"}},"required":["justification"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/correction-letter":{"post":{"summary":"Emite uma Carta de Correção (CC-e)","tags":["Fiscal Documents"],"description":"Emite uma Carta de Correção Eletrônica (evento 110110) para uma NF-e/NFC-e AUTORIZADA. Síncrono: aguarda a SEFAZ e devolve o resultado. Regras: texto de 15–1000 caracteres, prazo de 30 dias após a autorização, máximo de 20 correções por documento. Não se aplica a NFS-e e não corrige valores fiscais nem dados do emitente/destinatário.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"correction":{"type":"string","minLength":15,"maxLength":1000,"description":"Texto da correção (15–1000 caracteres)"}},"required":["correction"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"sequence":{"type":"integer","description":"Número sequencial do evento de correção"},"protocol":{"type":"string","description":"Protocolo do evento na SEFAZ"}},"required":["success","sequence","protocol"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/xml":{"get":{"summary":"Baixa o XML do documento fiscal","tags":["Fiscal Documents"],"description":"Retorna o XML autorizado (ou assinado com `?type=signed`). Use `?download=true` para forçar download como anexo. Resposta: `application/xml`.","parameters":[{"schema":{"type":"string","enum":["authorized","signed"]},"in":"query","name":"type","required":false,"description":"authorized (default) | signed"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false,"description":"Força Content-Disposition: attachment"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/danfe":{"get":{"summary":"Baixa a DANFE/DANFSe (PDF) do documento fiscal","tags":["Fiscal Documents"],"description":"Gera/retorna o PDF da DANFE (NF-e/NFC-e) ou DANFSe (NFS-e). Use `?download=true` para forçar download. Resposta: `application/pdf`.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do documento fiscal"}],"security":[{"apiKey":[]}],"responses":{"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"500":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-inutilizations":{"post":{"summary":"Inutiliza um intervalo de numeração de NF-e/NFC-e","tags":["Inutilizations"],"description":"Síncrono: valida, chama a SEFAZ e devolve o protocolo. A justificativa deve ter no mínimo 15 caracteres (regra SEFAZ).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"integer","minimum":0,"description":"Série"},"startNumber":{"type":"integer","minimum":1,"description":"Número inicial"},"endNumber":{"type":"integer","minimum":1,"description":"Número final"},"justification":{"type":"string","minLength":15,"description":"Justificativa (mín. 15 caracteres)"},"model":{"type":"string","enum":["55","65"],"description":"55 = NF-e (default), 65 = NFC-e"}},"required":["series","startNumber","endNumber","justification"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"protocol":{"type":"string","nullable":true},"record":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false}},"required":["success","protocol","record"],"additionalProperties":false}}}},"400":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"get":{"summary":"Lista as inutilizações de numeração da empresa","tags":["Inutilizations"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false,"description":"Página (1-based)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"pageSize","required":false,"description":"Itens por página (máx. 100)"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"series":{"type":"integer"},"model":{"type":"string","description":"55 = NF-e, 65 = NFC-e"},"startNumber":{"type":"integer"},"endNumber":{"type":"integer"},"year":{"type":"string","description":"Ano (2 dígitos)"},"status":{"type":"string","description":"PENDING | AUTHORIZED | REJECTED"},"protocol":{"type":"string","nullable":true},"justification":{"type":"string"},"inutilizationDate":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","series","model","startNumber","endNumber","year","status","protocol","justification","inutilizationDate","createdAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-inutilizations/{id}":{"get":{"summary":"Detalha uma inutilização pelo id","tags":["Inutilizations"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"series":{"type":"integer"},"model":{"type":"string","description":"55 = NF-e, 65 = NFC-e"},"startNumber":{"type":"integer"},"endNumber":{"type":"integer"},"year":{"type":"string","description":"Ano (2 dígitos)"},"status":{"type":"string","description":"PENDING | AUTHORIZED | REJECTED"},"protocol":{"type":"string","nullable":true},"justification":{"type":"string"},"inutilizationDate":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","series","model","startNumber","endNumber","year","status","protocol","justification","inutilizationDate","createdAt"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/tax-rules":{"get":{"summary":"Lista as regras tributárias da empresa","tags":["Tax Rules"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false,"description":"Página (1-based)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"pageSize","required":false,"description":"Itens por página (máx. 100)"},{"schema":{"type":"string","enum":["NFE","NFSE"]},"in":"query","name":"model","required":false,"description":"Filtra por modelo"},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false,"description":"Filtra por ativas/inativas"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"model":{"type":"string","description":"NFE | NFSE"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"states":{"type":"array","items":{"type":"string"}},"clientTypes":{"type":"array","items":{"type":"string"}},"icmsCst":{"type":"string"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"string","nullable":true},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"string","nullable":true},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"string","nullable":true},"ipiCEnq":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","isActive"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"string"},"issRetention":{"type":"boolean"},"pisRate":{"type":"string"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"string"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"string"},"irRetention":{"type":"boolean"},"inssRate":{"type":"string"},"inssRetention":{"type":"boolean"},"csllRate":{"type":"string"},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string"},"incidenceMunicipality":{"type":"string"},"isActive":{"type":"boolean"}},"required":["id","name","serviceLocation","operationNature","issRate","issRetention","pisRate","pisRetention","cofinsRate","cofinsRetention","irRate","irRetention","inssRate","inssRetention","csllRate","csllRetention","deductionsRate","additionalInfo","piscofinsCst","serviceLocationMunicipality","incidenceMunicipality","isActive"],"additionalProperties":false}}},"required":["id","name","model","isActive","createdAt","updatedAt","nfeTaxRules","nfseTaxRules"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria uma regra tributária","tags":["Tax Rules"],"description":"Cria uma regra (NF-e ou NFS-e) com suas sub-regras. O `id` retornado pode ser usado como `taxRuleId` em POST /v1/fiscal-documents.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome da regra"},"model":{"type":"string","enum":["NFE","NFSE"],"description":"Modelo fiscal da regra"},"isActive":{"type":"boolean"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Nome da sub-regra"},"states":{"type":"array","items":{"type":"string"},"description":"UFs do destinatário onde a regra vale (vazio = qualquer UF)"},"clientTypes":{"type":"array","items":{"type":"string","enum":["CONTRIBUINTE","NAO_CONTRIBUINTE","ESTRANGEIRO"]},"description":"Tipos de cliente em que a regra casa"},"icmsCst":{"type":"string","description":"CST/CSOSN do ICMS"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"number","nullable":true,"description":"Alíquota de PIS (%)"},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"number","nullable":true,"description":"Alíquota de COFINS (%)"},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"number","nullable":true,"description":"Alíquota de IPI (%)"},"ipiCEnq":{"type":"string","nullable":true,"description":"Código de enquadramento do IPI"},"isActive":{"type":"boolean"}},"required":["icmsCst"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string","enum":["NO_MUNICIPIO_EMPRESA","FORA_MUNICIPIO_EMPRESA","EXTERIOR"]}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"number","description":"Alíquota de ISS (%)"},"issRetention":{"type":"boolean"},"pisRate":{"type":"number"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"number"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"number","nullable":true},"irRetention":{"type":"boolean"},"inssRate":{"type":"number","nullable":true},"inssRetention":{"type":"boolean"},"csllRate":{"type":"number","nullable":true},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"number"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string","enum":["MUNICIPIO_PRESTACAO_SERVICO","MUNICIPIO_CLIENTE","MUNICIPIO_EMPRESA"],"description":"Município de prestação do serviço"},"incidenceMunicipality":{"type":"string","enum":["MUNICIPIO_PRESTACAO_SERVICO","MUNICIPIO_CLIENTE","MUNICIPIO_EMPRESA"],"description":"Município de incidência do ISS"},"isActive":{"type":"boolean"}},"required":["serviceLocationMunicipality","incidenceMunicipality"],"additionalProperties":false}}},"required":["name","model"],"additionalProperties":false,"description":"Regra tributária com suas sub-regras"}}},"description":"Regra tributária com suas sub-regras"},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"model":{"type":"string","description":"NFE | NFSE"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"states":{"type":"array","items":{"type":"string"}},"clientTypes":{"type":"array","items":{"type":"string"}},"icmsCst":{"type":"string"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"string","nullable":true},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"string","nullable":true},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"string","nullable":true},"ipiCEnq":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","isActive"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"string"},"issRetention":{"type":"boolean"},"pisRate":{"type":"string"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"string"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"string"},"irRetention":{"type":"boolean"},"inssRate":{"type":"string"},"inssRetention":{"type":"boolean"},"csllRate":{"type":"string"},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string"},"incidenceMunicipality":{"type":"string"},"isActive":{"type":"boolean"}},"required":["id","name","serviceLocation","operationNature","issRate","issRetention","pisRate","pisRetention","cofinsRate","cofinsRetention","irRate","irRetention","inssRate","inssRetention","csllRate","csllRetention","deductionsRate","additionalInfo","piscofinsCst","serviceLocationMunicipality","incidenceMunicipality","isActive"],"additionalProperties":false}}},"required":["id","name","model","isActive","createdAt","updatedAt","nfeTaxRules","nfseTaxRules"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/tax-rules/{id}":{"get":{"summary":"Detalha uma regra tributária","tags":["Tax Rules"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da regra tributária"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"model":{"type":"string","description":"NFE | NFSE"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"states":{"type":"array","items":{"type":"string"}},"clientTypes":{"type":"array","items":{"type":"string"}},"icmsCst":{"type":"string"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"string","nullable":true},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"string","nullable":true},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"string","nullable":true},"ipiCEnq":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","isActive"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"string"},"issRetention":{"type":"boolean"},"pisRate":{"type":"string"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"string"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"string"},"irRetention":{"type":"boolean"},"inssRate":{"type":"string"},"inssRetention":{"type":"boolean"},"csllRate":{"type":"string"},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string"},"incidenceMunicipality":{"type":"string"},"isActive":{"type":"boolean"}},"required":["id","name","serviceLocation","operationNature","issRate","issRetention","pisRate","pisRetention","cofinsRate","cofinsRetention","irRate","irRetention","inssRate","inssRetention","csllRate","csllRetention","deductionsRate","additionalInfo","piscofinsCst","serviceLocationMunicipality","incidenceMunicipality","isActive"],"additionalProperties":false}}},"required":["id","name","model","isActive","createdAt","updatedAt","nfeTaxRules","nfseTaxRules"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza uma regra tributária","tags":["Tax Rules"],"description":"Atualiza nome/modelo/ativação. Enviar `nfeTaxRules`/`nfseTaxRules` SUBSTITUI integralmente as sub-regras daquele modelo.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"model":{"type":"string","enum":["NFE","NFSE"]},"isActive":{"type":"boolean"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Nome da sub-regra"},"states":{"type":"array","items":{"type":"string"},"description":"UFs do destinatário onde a regra vale (vazio = qualquer UF)"},"clientTypes":{"type":"array","items":{"type":"string","enum":["CONTRIBUINTE","NAO_CONTRIBUINTE","ESTRANGEIRO"]},"description":"Tipos de cliente em que a regra casa"},"icmsCst":{"type":"string","description":"CST/CSOSN do ICMS"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"number","nullable":true,"description":"Alíquota de PIS (%)"},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"number","nullable":true,"description":"Alíquota de COFINS (%)"},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"number","nullable":true,"description":"Alíquota de IPI (%)"},"ipiCEnq":{"type":"string","nullable":true,"description":"Código de enquadramento do IPI"},"isActive":{"type":"boolean"}},"required":["icmsCst"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string","enum":["NO_MUNICIPIO_EMPRESA","FORA_MUNICIPIO_EMPRESA","EXTERIOR"]}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"number","description":"Alíquota de ISS (%)"},"issRetention":{"type":"boolean"},"pisRate":{"type":"number"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"number"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"number","nullable":true},"irRetention":{"type":"boolean"},"inssRate":{"type":"number","nullable":true},"inssRetention":{"type":"boolean"},"csllRate":{"type":"number","nullable":true},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"number"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string","enum":["MUNICIPIO_PRESTACAO_SERVICO","MUNICIPIO_CLIENTE","MUNICIPIO_EMPRESA"],"description":"Município de prestação do serviço"},"incidenceMunicipality":{"type":"string","enum":["MUNICIPIO_PRESTACAO_SERVICO","MUNICIPIO_CLIENTE","MUNICIPIO_EMPRESA"],"description":"Município de incidência do ISS"},"isActive":{"type":"boolean"}},"required":["serviceLocationMunicipality","incidenceMunicipality"],"additionalProperties":false}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da regra tributária"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"model":{"type":"string","description":"NFE | NFSE"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"},"nfeTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"states":{"type":"array","items":{"type":"string"}},"clientTypes":{"type":"array","items":{"type":"string"}},"icmsCst":{"type":"string"},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"pisCst":{"type":"string","nullable":true},"pisPPis":{"type":"string","nullable":true},"cofinsCst":{"type":"string","nullable":true},"cofinsPCofins":{"type":"string","nullable":true},"ipiCst":{"type":"string","nullable":true},"ipiPIpi":{"type":"string","nullable":true},"ipiCEnq":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","isActive"],"additionalProperties":false}},"nfseTaxRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"serviceLocation":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"issRate":{"type":"string"},"issRetention":{"type":"boolean"},"pisRate":{"type":"string"},"pisRetention":{"type":"boolean"},"cofinsRate":{"type":"string"},"cofinsRetention":{"type":"boolean"},"irRate":{"type":"string"},"irRetention":{"type":"boolean"},"inssRate":{"type":"string"},"inssRetention":{"type":"boolean"},"csllRate":{"type":"string"},"csllRetention":{"type":"boolean"},"deductionsRate":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"piscofinsCst":{"type":"string","nullable":true},"serviceLocationMunicipality":{"type":"string"},"incidenceMunicipality":{"type":"string"},"isActive":{"type":"boolean"}},"required":["id","name","serviceLocation","operationNature","issRate","issRetention","pisRate","pisRetention","cofinsRate","cofinsRetention","irRate","irRetention","inssRate","inssRetention","csllRate","csllRetention","deductionsRate","additionalInfo","piscofinsCst","serviceLocationMunicipality","incidenceMunicipality","isActive"],"additionalProperties":false}}},"required":["id","name","model","isActive","createdAt","updatedAt","nfeTaxRules","nfseTaxRules"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Remove uma regra tributária (soft delete)","tags":["Tax Rules"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da regra tributária"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks":{"get":{"summary":"Lista os endpoints de webhook da empresa","tags":["Webhooks"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Vazio = todos os eventos"},"isActive":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","isActive","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um endpoint de webhook","tags":["Webhooks"],"description":"Retorna o `secret` de assinatura UMA única vez. Use-o para validar o header `X-Conttrole-Signature: t=<ts>,v1=<hmac>` (HMAC-SHA256 de `<ts>.<corpo>`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL HTTPS que recebe os eventos"},"description":{"type":"string","maxLength":255},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Eventos assinados. Omitido/vazio = todos."}},"required":["url"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Vazio = todos os eventos"},"isActive":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura — exibido apenas uma vez. Guarde-o."}},"required":["id","url","description","events","isActive","createdAt","updatedAt","secret"],"additionalProperties":false}}}},"400":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/{id}":{"get":{"summary":"Detalha um endpoint de webhook","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Vazio = todos os eventos"},"isActive":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","isActive","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza um endpoint de webhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":255,"nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"}},"isActive":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Vazio = todos os eventos"},"isActive":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","isActive","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"422":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Remove um endpoint de webhook","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"summary":"Gera um novo segredo de assinatura","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"description":"Vazio = todos os eventos"},"isActive":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura — exibido apenas uma vez. Guarde-o."}},"required":["id","url","description","events","isActive","createdAt","updatedAt","secret"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/{id}/test":{"post":{"summary":"Envia um evento de teste para o endpoint","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string"}},"required":["deliveryId"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver":{"post":{"summary":"Reenvia uma entrega específica","tags":["Webhooks"],"description":"Reenfileira a entrega (volta para PENDING e dispara a task de novo). Útil para reenviar manualmente uma entrega que falhou.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"deliveryId","required":true}],"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string"},"requeued":{"type":"boolean","enum":[true]}},"required":["deliveryId","requeued"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"summary":"Lista as entregas recentes de um endpoint","tags":["Webhooks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED"],"description":"Evento assinado pelo endpoint"},"eventId":{"type":"string"},"status":{"type":"string","description":"PENDING | SUCCEEDED | FAILED"},"attempts":{"type":"integer"},"responseStatus":{"type":"integer","nullable":true},"responseBody":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"deliveredAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","eventType","eventId","status","attempts","responseStatus","responseBody","errorMessage","deliveredAt","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"403":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"404":{"description":"Erro padrão da API","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"error":{"type":"string","description":"Nome curto do erro (ex: Unauthorized)"},"message":{"type":"string","description":"Mensagem legível explicando a falha"},"code":{"type":"string","description":"Código de erro estável da aplicação (ex: invalid_api_key)"}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}}},"servers":[{"url":"https://api.conttrole.io"}],"tags":[{"name":"Health","description":"Status e disponibilidade do serviço"},{"name":"Fiscal Documents","description":"Consulta, download (XML/DANFE) e cancelamento de documentos fiscais"},{"name":"Inutilizations","description":"Inutilização de intervalos de numeração de NF-e/NFC-e"},{"name":"Webhooks","description":"Endpoints de webhook e entregas de eventos fiscais (autorização, rejeição, cancelamento, inutilização)"},{"name":"Tax Rules","description":"Regras tributárias (NF-e/NFS-e) da empresa — usadas para preencher impostos ao criar documentos"}]}