{"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/accounting/office":{"get":{"summary":"O escritório da chave","tags":["Accounting"],"description":"Dados do escritório dono da chave, quantas empresas estão na carteira e os escopos da própria chave. Use como verificação de conexão.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"crcNumber":{"type":"string","nullable":true},"crcUf":{"type":"string","nullable":true},"status":{"type":"string","description":"ACTIVE — suspenso não chega aqui (403)"},"companyCount":{"type":"integer","description":"Empresas com vínculo ativo"},"key":{"type":"object","properties":{"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["name","prefix","scopes"],"additionalProperties":false}},"required":["id","name","crcNumber","crcUf","status","companyCount","key"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/office/key":{"delete":{"summary":"Revoga a própria chave (desconectar)","tags":["Accounting"],"description":"Revoga a chave usada na chamada. É o 'Desconectar' de um sistema integrado: vale para qualquer escopo e com o escritório suspenso. Chaves de outras integrações do escritório não são tocadas.","security":[{"apiKey":[]}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies":{"get":{"summary":"Lista as empresas da carteira","tags":["Accounting"],"description":"Só as empresas com vínculo ATIVO com o escritório. A empresa que encerra o vínculo sai desta lista — e do alcance da chave — na hora.","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":"search","required":false,"description":"Trecho do nome ou do CNPJ"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Use como `companyId` nas rotas por empresa"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"taxId":{"type":"string"},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"crtCode":{"type":"string","nullable":true,"description":"1 Simples · 2 excesso de sublimite · 3 Normal · 4 MEI"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobile":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"linkedSince":{"type":"string","nullable":true,"description":"Quando o vínculo foi aceito (ISO)"},"officeIssuingAllowed":{"type":"boolean","description":"A empresa permite que o escritório emita e cancele notas dela pela integração. `false` = as rotas de escrita de `fiscal-documents` respondem 403 `office_issuing_not_allowed` (a leitura continua). Quem muda é a empresa, no app; a mudança chega no webhook `link.updated`."}},"required":["id","name","tradingName","taxId","stateRegistration","municipalRegistration","crtCode","email","phone","mobile","zipCode","street","number","complement","neighborhood","municipalityCode","city","state","linkedSince","officeIssuingAllowed"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}":{"get":{"summary":"Detalha uma empresa da carteira","tags":["Accounting"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Use como `companyId` nas rotas por empresa"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"taxId":{"type":"string"},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"crtCode":{"type":"string","nullable":true,"description":"1 Simples · 2 excesso de sublimite · 3 Normal · 4 MEI"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobile":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"linkedSince":{"type":"string","nullable":true,"description":"Quando o vínculo foi aceito (ISO)"},"officeIssuingAllowed":{"type":"boolean","description":"A empresa permite que o escritório emita e cancele notas dela pela integração. `false` = as rotas de escrita de `fiscal-documents` respondem 403 `office_issuing_not_allowed` (a leitura continua). Quem muda é a empresa, no app; a mudança chega no webhook `link.updated`."}},"required":["id","name","tradingName","taxId","stateRegistration","municipalRegistration","crtCode","email","phone","mobile","zipCode","street","number","complement","neighborhood","municipalityCode","city","state","linkedSince","officeIssuingAllowed"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/closings/eligible":{"get":{"summary":"Empresas da carteira com movimento no mês","tags":["Accounting"],"description":"Quem tem ao menos uma nota de PRODUÇÃO autorizada ou cancelada no mês (BRT) — o mesmo critério do pedido de fechamento, que pula o mês vazio.","parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"year","required":false},{"schema":{"type":"integer","minimum":1,"maximum":12},"in":"query","name":"month","required":false,"description":"1–12"}],"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"},"tradingName":{"type":"string","nullable":true},"taxId":{"type":"string"},"documentCount":{"type":"integer"}},"required":["id","name","tradingName","taxId","documentCount"],"additionalProperties":false}}},"required":["data"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/closings":{"get":{"summary":"Lista os fechamentos fiscais da carteira","tags":["Accounting"],"description":"Os pedidos de fechamento (um ZIP por empresa × mês), do painel e da API. Só de empresas que estão na carteira HOJE.","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":"companyId","required":false},{"schema":{"type":"integer"},"in":"query","name":"year","required":false},{"schema":{"type":"integer","minimum":1,"maximum":12},"in":"query","name":"month","required":false,"description":"1–12"},{"schema":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"]},"in":"query","name":"status","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"year":{"type":"integer"},"month":{"type":"integer","description":"1–12"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"]},"includeXml":{"type":"boolean"},"includePdf":{"type":"boolean"},"fileName":{"type":"string","nullable":true},"documentCount":{"type":"integer","nullable":true},"fileCount":{"type":"integer","nullable":true},"errorMessage":{"type":"string","nullable":true},"requestedVia":{"type":"string","enum":["app","api"],"description":"`api` = pedido pela API com a chave do escritório; `app` = pedido por uma pessoa no app (contador ou a própria empresa)"},"createdAt":{"type":"string"},"completedAt":{"type":"string","nullable":true}},"required":["id","companyId","year","month","status","includeXml","includePdf","fileName","documentCount","fileCount","errorMessage","requestedVia","createdAt","completedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Pede o fechamento fiscal de um mês","tags":["Accounting"],"description":"Gera um ZIP por empresa (XML e/ou DANFE das notas de PRODUÇÃO autorizadas e canceladas no mês, em BRT). Assíncrono: responde 202 e cada fechamento aparece em `GET /v1/accounting/closings`; baixe por `GET /v1/accounting/closings/{id}/download` quando estiver COMPLETED. Sem `companyIds`, vale para a carteira inteira. Empresa com fechamento do mesmo mês em andamento, sem nota no mês ou fora da carteira volta em `skipped`, com o motivo.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100,"nullable":true},"month":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"1–12"},"companyIds":{"type":"array","items":{"type":"string"},"maxItems":200,"nullable":true},"includeXml":{"type":"boolean","nullable":true,"description":"Default true"},"includePdf":{"type":"boolean","nullable":true,"description":"Default true"}},"additionalProperties":false,"nullable":true}]}}}},"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"companyId":{"type":"string"},"closingId":{"type":"string"}},"required":["companyId","closingId"],"additionalProperties":false}},"skipped":{"type":"array","items":{"type":"object","properties":{"companyId":{"type":"string"},"reason":{"type":"string"},"code":{"type":"string","enum":["already_running","no_documents","dispatch_failed","not_in_portfolio","not_found"]}},"required":["companyId","reason","code"],"additionalProperties":false}}},"required":["created","skipped"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/closings/{id}":{"get":{"summary":"Situação de um fechamento","tags":["Accounting"],"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"},"companyId":{"type":"string"},"year":{"type":"integer"},"month":{"type":"integer","description":"1–12"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"]},"includeXml":{"type":"boolean"},"includePdf":{"type":"boolean"},"fileName":{"type":"string","nullable":true},"documentCount":{"type":"integer","nullable":true},"fileCount":{"type":"integer","nullable":true},"errorMessage":{"type":"string","nullable":true},"requestedVia":{"type":"string","enum":["app","api"],"description":"`api` = pedido pela API com a chave do escritório; `app` = pedido por uma pessoa no app (contador ou a própria empresa)"},"createdAt":{"type":"string"},"completedAt":{"type":"string","nullable":true}},"required":["id","companyId","year","month","status","includeXml","includePdf","fileName","documentCount","fileCount","errorMessage","requestedVia","createdAt","completedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/closings/{id}/download":{"get":{"summary":"Link de download do ZIP do fechamento","tags":["Accounting"],"description":"Devolve um link assinado, válido por 1 hora. Só para fechamento COMPLETED; antes disso a resposta é 409 com a situação atual.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"fileName":{"type":"string","nullable":true},"expiresAt":{"type":"string"}},"required":["url","fileName","expiresAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/received-documents/export":{"get":{"summary":"Baixa as notas recebidas do mês de VÁRIAS empresas num ZIP","tags":["Accounting"],"description":"O download em lote da carteira: uma pasta por empresa (`<CNPJ> - <razão social>/notas/...`), com a mesma estrutura do ZIP por empresa. Sem `companyIds`, vale para a carteira inteira (até 200 empresas; acima disso, peça em lotes). Empresa sem nota no mês não ganha pasta. `X-Company-Count` diz quantas vieram. Todas as notas recebidas de uma competência (mês de EMISSÃO, em BRT) num ZIP só: `notas/`, `eventos/` e, se pedidos, `resumos/`. Cada arquivo é `<chave>-nsu<NSU>.xml`. O ZIP é montado enquanto é baixado (não há limite de notas), e os headers `X-Document-Count` e `X-Pending-Summaries` chegam antes do corpo. `X-Pending-Summaries` > 0 significa NF-e das quais só existe o resumo: manifeste a Ciência (`POST .../{id}/manifestation`) e sincronize para receber o XML completo. Mês sem nada responde 404 `no_documents`. Resposta: `application/zip`. Exige a chave do escritório com `received-documents:read`.","parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"year","required":false},{"schema":{"type":"integer","minimum":1,"maximum":12},"in":"query","name":"month","required":false,"description":"1–12"},{"schema":{"type":"boolean"},"in":"query","name":"notes","required":false,"description":"NF-e completas (`nfeProc`) e NFS-e. Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"events","required":false,"description":"Eventos (cancelamento, CC-e, manifestações, eventos de NFS-e). Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"summaries","required":false,"description":"RESUMOS (`resNFe`) das NF-e ainda não manifestadas — só dados básicos, sem a nota. Default `false`: para escrituração eles não servem, e o header `X-Pending-Summaries` diz quantos ficaram de fora."},{"schema":{"type":"string"},"in":"query","name":"companyIds","required":false,"description":"IDs separados por vírgula (`GET /v1/accounting/companies`). Omita para a carteira inteira."}],"security":[{"apiKey":[]}],"responses":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/received-documents/export/link":{"post":{"summary":"Gera um link de download do ZIP do mês de VÁRIAS empresas","tags":["Accounting"],"description":"O lote da carteira (`GET /v1/accounting/received-documents/export`) em forma de link — uma pasta por empresa. Em vez do ZIP, devolve um LINK que baixa o ZIP sem header de autenticação — para abrir no navegador ou entregar a uma pessoa (é o que o MCP usa). Vale por 15 minutos. 🔴 A credencial que pediu o link é conferida de novo no download: chave revogada, acesso desligado ou empresa que saiu da carteira derrubam o link na hora (`403 link_revoked`). Os números (`documentCount`, `pendingSummaries`) são os do ZIP. Mês sem nada responde 404 `no_documents`. Exige a chave do escritório com `received-documents:read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100,"nullable":true},"month":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"1–12"},"notes":{"type":"boolean","nullable":true,"description":"NF-e completas e NFS-e. Default `true`."},"events":{"type":"boolean","nullable":true,"description":"Eventos das notas. Default `true`."},"summaries":{"type":"boolean","nullable":true,"description":"Resumos das NF-e ainda não manifestadas. Default `false`."},"companyIds":{"type":"array","items":{"type":"string"},"maxItems":200,"nullable":true,"description":"Omita para a carteira inteira (até 200 empresas)."}},"additionalProperties":false,"nullable":true}]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Abre direto no navegador e baixa o ZIP — sem header de autenticação. Vale por 15 minutos e pode ser usado mais de uma vez nesse prazo."},"fileName":{"type":"string"},"expiresAt":{"type":"string","description":"ISO 8601"},"documentCount":{"type":"integer","description":"Documentos que vão no ZIP"},"companyCount":{"type":"integer","description":"Empresas com ao menos um documento"},"pendingSummaries":{"type":"integer","description":"NF-e das quais só existe o resumo — manifeste a Ciência para receber a nota"}},"required":["url","fileName","expiresAt","documentCount","companyCount","pendingSummaries"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/suspicious":{"get":{"summary":"Notas recebidas que a empresa pode não reconhecer","tags":["Accounting"],"description":"NF-e recebidas nos últimos 60 dias, ainda sem decisão (sem manifestação ou só Ciência), de um fornecedor que NUNCA emitiu para a empresa e que também fogem do padrão: valor acima de 5× a mediana das notas recebidas nos 12 meses anteriores (piso de R$ 1.000) ou mercadoria de capítulo de NCM fora do ramo. Pode ser nota fria contra o CNPJ — se a compra não aconteceu, manifeste Desconhecimento da operação (`210220`). Empresa com menos de 10 notas de histórico não tem suspeitas. É convite a conferir, nunca acusação. Chave do escritório com `received-documents:read`; a empresa precisa estar na carteira (vínculo ativo).","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","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"},"accessKey":{"type":"string","nullable":true},"issuerCnpj":{"type":"string","nullable":true},"issuerName":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true},"emitDate":{"type":"string","nullable":true},"manifestation":{"type":"string"},"reasons":{"type":"array","items":{"type":"string","enum":["fornecedor_novo","valor_atipico","ramo_diferente"]}}},"required":["id","accessKey","issuerCnpj","issuerName","documentNumber","totalValue","emitDate","manifestation","reasons"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents":{"get":{"summary":"Lista as notas recebidas (DF-e) da empresa","tags":["Accounting"],"description":"Notas emitidas CONTRA o CNPJ da empresa (fornecedores), baixadas pela Distribuição DF-e (NF-e) e pelo ADN (NFS-e do Padrão Nacional). Ordenadas por NSU decrescente. Use `pending=true` para a fila de manifestação: NF-e com chave e ainda sem manifestação. **Sincronização:** com `changedSince` (ou `cursor`) a lista vira a das notas CRIADAS OU ALTERADAS desde aquele instante — chegada do XML completo, manifestação, cancelamento —, em ordem de alteração, e `page` é ignorado: siga `meta.nextCursor` enquanto `meta.hasMore` for verdadeiro e GUARDE o último `nextCursor` — ele é o marco da próxima rodada (página vazia devolve o mesmo cursor recebido). Chave do escritório com `received-documents:read`; a empresa precisa estar na carteira (vínculo ativo).","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},{"schema":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"]},"in":"query","name":"schemaType","required":false},{"schema":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"in":"query","name":"manifestation","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"pending","required":false,"description":"true = só o que precisa de manifestação (ignora model/schemaType/manifestation)"},{"schema":{"type":"string"},"in":"query","name":"accessKey","required":false,"description":"Chave de acesso exata (44 dígitos)"},{"schema":{"type":"string"},"in":"query","name":"issuerCnpj","required":false,"description":"CNPJ do emitente (só dígitos ou formatado)"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Trecho da chave, do CNPJ ou do nome do emitente"},{"schema":{"type":"string","format":"date"},"in":"query","name":"emittedFrom","required":false,"description":"Emitidas a partir de (YYYY-MM-DD, BRT)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"emittedTo","required":false,"description":"Emitidas até (YYYY-MM-DD, BRT, inclusive)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"changedSince","required":false,"description":"Sincronização: notas criadas ou alteradas a partir deste instante (ISO 8601). Ignora `page`"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false,"description":"Sincronização: o `meta.nextCursor` da página anterior. Tem precedência sobre `changedSince`"},{"schema":{"type":"string"},"in":"path","name":"companyId","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"},"nsu":{"type":"string","description":"NSU da distribuição. NF-e e NFS-e têm sequências INDEPENDENTES — o mesmo NSU pode aparecer nos dois modelos."},"model":{"type":"string","enum":["NFE","NFSE"],"description":"NFE (Distribuição DF-e) | NFSE (ADN nacional)"},"schemaType":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"],"description":"RES_NFE = só o RESUMO (manifeste Ciência para liberar o XML completo) · PROC_NFE = NF-e completa · RES_EVENTO/PROC_EVENTO = evento de uma NF-e · NFSE / EVENTO_NFSE = NFS-e do Padrão Nacional e seus eventos"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"issuerCnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente (o fornecedor)"},"issuerName":{"type":"string","nullable":true},"issuerStateReg":{"type":"string","nullable":true},"recipientCnpj":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"documentSeries":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"emitDate":{"type":"string","nullable":true,"description":"Emissão (ISO 8601)"},"situationCode":{"type":"string","nullable":true,"description":"cSitNFe: 1 = autorizada, 2 = cancelada, 3 = denegada"},"protocolNumber":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true,"description":"tpEvento, quando o documento é um evento"},"eventDescription":{"type":"string","nullable":true},"hasFullXml":{"type":"boolean","description":"true = o XML completo está disponível (e a DANFE pode ser gerada)"},"manifestation":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"manifestationDate":{"type":"string","nullable":true},"manifestationProtocol":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"Quando a nota chegou à Conttrole"},"updatedAt":{"type":"string"}},"required":["id","nsu","model","schemaType","accessKey","issuerCnpj","issuerName","issuerStateReg","recipientCnpj","documentNumber","documentSeries","totalValue","emitDate","situationCode","protocolNumber","eventType","eventDescription","hasFullXml","manifestation","manifestationDate","manifestationProtocol","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Só na sincronização: posição depois da última nota entregue. Guarde-o mesmo no fim — é o marco da próxima rodada"},"hasMore":{"type":"boolean","description":"Só na sincronização: há mais notas depois desta página"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/distribution":{"get":{"summary":"Estado da distribuição DF-e da empresa","tags":["Accounting"],"description":"Cursor de NSU, último cStat e quando o próximo `POST /sync` é permitido. A distribuição roda sozinha a cada hora; use isto para saber se ela está andando antes de disparar uma manual.","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false = a distribuição automática foi desligada para a empresa"},"hasCertificate":{"type":"boolean","description":"Sem certificado A1 a distribuição não roda (mTLS com a SEFAZ)"},"nfe":{"type":"object","properties":{"lastNsu":{"type":"string"},"maxNsu":{"type":"string"},"lastRunAt":{"type":"string","nullable":true},"lastStatus":{"type":"string","nullable":true,"description":"cStat da última consulta (137/138/656…)"},"lastMotive":{"type":"string","nullable":true},"nextSyncAllowedAt":{"type":"string","nullable":true,"description":"Antes disto o `POST /received-documents/sync` responde 429: a SEFAZ exige 1h de espera depois de 137/656. `null` = pode sincronizar."}},"required":["lastNsu","maxNsu","lastRunAt","lastStatus","lastMotive","nextSyncAllowedAt"],"additionalProperties":false},"nfse":{"type":"object","properties":{"lastNsu":{"type":"string"},"maxNsu":{"type":"string"},"lastRunAt":{"type":"string","nullable":true},"lastStatus":{"type":"string","nullable":true},"lastMotive":{"type":"string","nullable":true}},"required":["lastNsu","maxNsu","lastRunAt","lastStatus","lastMotive"],"additionalProperties":false}},"required":["enabled","hasCertificate","nfe","nfse"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/export":{"get":{"summary":"Baixa as notas recebidas do mês num ZIP (lote)","tags":["Accounting"],"description":"Todas as notas recebidas de uma competência (mês de EMISSÃO, em BRT) num ZIP só: `notas/`, `eventos/` e, se pedidos, `resumos/`. Cada arquivo é `<chave>-nsu<NSU>.xml`. O ZIP é montado enquanto é baixado (não há limite de notas), e os headers `X-Document-Count` e `X-Pending-Summaries` chegam antes do corpo. `X-Pending-Summaries` > 0 significa NF-e das quais só existe o resumo: manifeste a Ciência (`POST .../{id}/manifestation`) e sincronize para receber o XML completo. Mês sem nada responde 404 `no_documents`. Resposta: `application/zip`. Chave do escritório com `received-documents:read`; a empresa precisa estar na carteira (vínculo ativo).","parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"year","required":false},{"schema":{"type":"integer","minimum":1,"maximum":12},"in":"query","name":"month","required":false,"description":"1–12"},{"schema":{"type":"boolean"},"in":"query","name":"notes","required":false,"description":"NF-e completas (`nfeProc`) e NFS-e. Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"events","required":false,"description":"Eventos (cancelamento, CC-e, manifestações, eventos de NFS-e). Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"summaries","required":false,"description":"RESUMOS (`resNFe`) das NF-e ainda não manifestadas — só dados básicos, sem a nota. Default `false`: para escrituração eles não servem, e o header `X-Pending-Summaries` diz quantos ficaram de fora."},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/export/link":{"post":{"summary":"Gera um link de download do ZIP do mês (sem header de autenticação)","tags":["Accounting"],"description":"Em vez do ZIP, devolve um LINK que baixa o ZIP sem header de autenticação — para abrir no navegador ou entregar a uma pessoa (é o que o MCP usa). Vale por 15 minutos. 🔴 A credencial que pediu o link é conferida de novo no download: chave revogada, acesso desligado ou empresa que saiu da carteira derrubam o link na hora (`403 link_revoked`). Os números (`documentCount`, `pendingSummaries`) são os do ZIP. Mês sem nada responde 404 `no_documents`. Chave do escritório com `received-documents:read`; a empresa precisa estar na carteira (vínculo ativo).","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100,"nullable":true},"month":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"1–12"},"notes":{"type":"boolean","nullable":true,"description":"NF-e completas e NFS-e. Default `true`."},"events":{"type":"boolean","nullable":true,"description":"Eventos das notas. Default `true`."},"summaries":{"type":"boolean","nullable":true,"description":"Resumos das NF-e ainda não manifestadas. Default `false`."}},"additionalProperties":false,"nullable":true}]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Abre direto no navegador e baixa o ZIP — sem header de autenticação. Vale por 15 minutos e pode ser usado mais de uma vez nesse prazo."},"fileName":{"type":"string"},"expiresAt":{"type":"string","description":"ISO 8601"},"documentCount":{"type":"integer","description":"Documentos que vão no ZIP"},"companyCount":{"type":"integer","description":"Empresas com ao menos um documento"},"pendingSummaries":{"type":"integer","description":"NF-e das quais só existe o resumo — manifeste a Ciência para receber a nota"}},"required":["url","fileName","expiresAt","documentCount","companyCount","pendingSummaries"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/sync":{"post":{"summary":"Dispara a distribuição DF-e agora","tags":["Accounting"],"description":"Busca na SEFAZ (NF-e) e no ADN (NFS-e) os documentos novos emitidos contra a empresa. Assíncrono: responde 202 e as notas aparecem em `GET /received-documents` em instantes. A distribuição já roda a cada hora — isto é para quando não dá para esperar. Depois de uma consulta sem novidades (cStat 137) a SEFAZ exige 1h de espera; dentro dela a resposta é 429 com `Retry-After`, porque insistir faria a SEFAZ bloquear a empresa (cStat 656). Se já houver uma sincronização em andamento, a resposta é 202 com `runId: null` — o pedido é atendido por ela.","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"runId":{"type":"string","nullable":true},"message":{"type":"string"}},"required":["accepted","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/{id}":{"get":{"summary":"Detalha uma nota recebida","tags":["Accounting"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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"},"nsu":{"type":"string","description":"NSU da distribuição. NF-e e NFS-e têm sequências INDEPENDENTES — o mesmo NSU pode aparecer nos dois modelos."},"model":{"type":"string","enum":["NFE","NFSE"],"description":"NFE (Distribuição DF-e) | NFSE (ADN nacional)"},"schemaType":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"],"description":"RES_NFE = só o RESUMO (manifeste Ciência para liberar o XML completo) · PROC_NFE = NF-e completa · RES_EVENTO/PROC_EVENTO = evento de uma NF-e · NFSE / EVENTO_NFSE = NFS-e do Padrão Nacional e seus eventos"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"issuerCnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente (o fornecedor)"},"issuerName":{"type":"string","nullable":true},"issuerStateReg":{"type":"string","nullable":true},"recipientCnpj":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"documentSeries":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"emitDate":{"type":"string","nullable":true,"description":"Emissão (ISO 8601)"},"situationCode":{"type":"string","nullable":true,"description":"cSitNFe: 1 = autorizada, 2 = cancelada, 3 = denegada"},"protocolNumber":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true,"description":"tpEvento, quando o documento é um evento"},"eventDescription":{"type":"string","nullable":true},"hasFullXml":{"type":"boolean","description":"true = o XML completo está disponível (e a DANFE pode ser gerada)"},"manifestation":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"manifestationDate":{"type":"string","nullable":true},"manifestationProtocol":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"Quando a nota chegou à Conttrole"},"updatedAt":{"type":"string"},"pdf":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":"string","nullable":true,"description":"Por que o PDF não pode ser gerado — e o que fazer"}},"required":["available","reason"],"additionalProperties":false,"description":"Se `GET /received-documents/{id}/danfe` vai funcionar. Resumo não tem DANFE; evento também não."}},"required":["id","nsu","model","schemaType","accessKey","issuerCnpj","issuerName","issuerStateReg","recipientCnpj","documentNumber","documentSeries","totalValue","emitDate","situationCode","protocolNumber","eventType","eventDescription","hasFullXml","manifestation","manifestationDate","manifestationProtocol","createdAt","updatedAt","pdf"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/{id}/xml":{"get":{"summary":"Baixa o XML da nota recebida","tags":["Accounting"],"description":"O XML que chegou pela distribuição: o RESUMO (`resNFe`) enquanto a NF-e não foi manifestada, a nota completa (`nfeProc`) depois da Ciência, ou o evento. Confira `schemaType`/`hasFullXml` para saber qual é. Resposta: `application/xml`.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false,"description":"Força Content-Disposition: attachment"},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/{id}/danfe":{"get":{"summary":"Gera a DANFE/DANFSe (PDF) da nota recebida","tags":["Accounting"],"description":"Só existe com o XML COMPLETO (`hasFullXml`). Resumo de NF-e responde 409 dizendo para manifestar a Ciência; evento responde 409 porque não tem DANFE. Resposta: `application/pdf`.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/received-documents/{id}/manifestation":{"post":{"summary":"Manifesta a nota recebida (MD-e)","tags":["Accounting"],"description":"Envia à SEFAZ, EM NOME DA EMPRESA, a manifestação do destinatário. **É ato jurídico e não tem desfazer.** CIENCIA (210210) libera o XML completo; CONFIRMADA (210200) declara que a operação aconteceu; DESCONHECIDA (210220) e NAO_REALIZADA (210240) recusam a nota — e cancelam a conta a pagar gerada por ela (com baixa, vira pendência). NAO_REALIZADA exige `justification` de 15+ caracteres. Só NF-e: NFS-e não tem manifestação. Chave do escritório com `received-documents:write`; a empresa precisa estar na carteira (vínculo ativo).","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"type":{"type":"string","enum":["CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"],"nullable":true},"justification":{"type":"string","maxLength":255,"nullable":true}},"additionalProperties":false,"nullable":true}]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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]},"manifestation":{"type":"string","enum":["CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"protocol":{"type":"string","nullable":true}},"required":["success","manifestation","protocol"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents":{"get":{"summary":"Lista documentos fiscais da empresa","tags":["Accounting"],"description":"Ordenadas pela emissão, da mais recente. **Sincronização:** com `changedSince` (ou `cursor`) a lista vira a das notas CRIADAS OU ALTERADAS desde aquele instante — autorização, rejeição, cancelamento, CC-e —, em ordem de alteração, e `page` é ignorado: siga `meta.nextCursor` enquanto `meta.hasMore` for verdadeiro e GUARDE o último `nextCursor` — ele é o marco da próxima rodada (página vazia devolve o mesmo cursor recebido). Os filtros (`status`, `type`, `environment`, `externalId`) valem nos dois modos. Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo).","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":["DRAFT","PROCESSING","AUTHORIZED","REJECTED","CANCELLED","DENIED","INUTILIZED"]},"in":"query","name":"status","required":false,"description":"Filtra por status (ex: AUTHORIZED, DRAFT)"},{"schema":{"type":"string","enum":["NFE","NFCE","NFSE"]},"in":"query","name":"type","required":false,"description":"Filtra por tipo (NFE/NFCE/NFSE)"},{"schema":{"type":"string","enum":["PRODUCTION","HOMOLOGATION","ALL"],"default":"PRODUCTION"},"in":"query","name":"environment","required":false,"description":"Ambiente das notas. Padrão PRODUCTION — documento de homologação (teste, sem valor fiscal) só aparece com HOMOLOGATION ou ALL."},{"schema":{"type":"string","maxLength":255},"in":"query","name":"externalId","required":false,"description":"Só as notas com este `externalId` (o id da venda no seu sistema), exato"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"changedSince","required":false,"description":"Sincronização: notas criadas ou alteradas a partir deste instante (ISO 8601). Ignora `page`"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false,"description":"Sincronização: o `meta.nextCursor` da página anterior. Tem precedência sobre `changedSince`"},{"schema":{"type":"string"},"in":"path","name":"companyId","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"},"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Só na sincronização: posição depois da última nota entregue. Guarde-o mesmo no fim — é o marco da próxima rodada"},"hasMore":{"type":"boolean","description":"Só na sincronização: há mais notas depois desta página"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um documento fiscal (rascunho)","tags":["Accounting"],"description":"Cria uma NF-e (modelo 55), NFC-e (modelo 65) ou NFS-e em DRAFT a partir de um cliente e dos itens informados. Identifique o cliente por `clientId` (já cadastrado) OU por `client` (objeto inline, que cria/reusa o cliente na hora — reusa quando o `document` casa). Cada imposto do item é resolvido CAMPO A CAMPO, do mais específico ao mais genérico: o que vier no ITEM (a nota sempre prevalece) → a Regra Fiscal indicada (`taxRuleId` do item, senão do documento, senão a vinculada ao produto) → a tributação própria do PRODUTO (`productId` — ver GET /v1/products) → o template fiscal (`templateId`) → as regras padrão da empresa (GET /v1/tax-rules). A regra casa por UF, tipo de cliente e CFOP da operação. NCM e CFOP ausentes vêm do produto e, sem produto, da empresa. O `templateId` (ver GET /v1/fiscal-templates) também pré-preenche natureza da operação e código de serviço nos campos não informados. Use `emit: true` para já disparar a emissão (assíncrona) — ou chame depois `POST /fiscal-documents/{id}/emit`. **Idempotência:** mande o header `Idempotency-Key` (1–100 caracteres `[A-Za-z0-9_.:-]`, único por empresa) para repetir a chamada sem risco de nota em dobro: a mesma chave com o mesmo corpo responde **200** com a nota JÁ criada (header `Idempotent-Replayed: true`), sem criar nem emitir de novo; com outro corpo, **422** `idempotency_key_mismatch`. Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento"},"clientId":{"type":"string","nullable":true,"description":"ID de um cliente já cadastrado nesta empresa. Informe `clientId` OU `client` (um dos dois é obrigatório)."},"client":{"type":"object","properties":{"name":{"type":"string","description":"Nome/razão social do cliente"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (só dígitos ou formatado). Se casar um cliente já existente desta empresa, ele é reusado (idempotente). Pode ser vazio (consumidor final) — SEFAZ aceita NF-e sem identificação."},"documentType":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"],"nullable":true,"description":"Tipo do documento. Inferido pelo documento quando omitido."},"type":{"type":"string","enum":["INDIVIDUAL","COMPANY","FOREIGN"],"nullable":true,"description":"Tipo do cliente. Inferido pelo documento quando omitido."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual"},"municipalRegistration":{"type":"string","nullable":true,"description":"Inscrição municipal"},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro"},"number":{"type":"string","nullable":true,"description":"Número"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true,"description":"UF (2 letras)"},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"country":{"type":"string","nullable":true,"description":"País. Default: Brasil."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (BACEN). Default: 1058 (Brasil)."}},"required":["name"],"additionalProperties":false,"nullable":true,"description":"Cliente inline — cria/reusa o cliente junto da nota. Alternativa ao `clientId`. Reusa um cliente existente quando o `document` casa."},"operationNature":{"type":"string","description":"Natureza da operação (<natOp>, até 60 caracteres). Ausente = a declarada pela regra fiscal do item; sem ela, 'Venda de mercadoria' (NF-e/NFC-e) ou 'Prestação de serviços' (NFS-e)."},"buyerPresence":{"type":"string","enum":["0","1","2","3","4","5","9"],"nullable":true,"description":"<indPres> — presença do comprador. 0=não se aplica · 1=presencial · 2=internet · 3=teleatendimento · 4=entrega a domicílio (NFC-e) · 5=presencial fora do estabelecimento · 9=não presencial, outros. Omita para automático: vale o padrão da empresa e, sem ele, a origem do documento (integração=2 na NF-e e 4 na NFC-e; manual=2/1). A NFC-e só aceita 1, 4 e 5 — outro valor é recusado com 422."},"issExigibility":{"type":"string","enum":["1","2","3","4","5","6","7"],"nullable":true,"description":"Exigibilidade do ISS (NFS-e). 1=exigível · 2=não incidência · 3=isenção · 4=exportação de serviço · 5=imunidade · 6=suspensa por decisão judicial · 7=suspensa por processo administrativo. Omita para herdar a regra fiscal de NFS-e e, sem ela, exigível. As duas suspensões (6 e 7) exigem `issSuspensionProcess` — sem ele, 422."},"issSuspensionProcess":{"type":"string","nullable":true,"description":"Número do processo que concedeu a suspensão. Obrigatório com issExigibility 6 ou 7; ignorado nas demais."},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true,"description":"<mdPrestacao> — 0=desconhecido · 1=transfronteiriço · 2=consumo no Brasil · 3=presença comercial no exterior · 4=movimento temporário de pessoas físicas."},"vinculoEntrePartes":{"type":"string","nullable":true,"description":"<vincPrest> — 0=sem vínculo · 1=controlada · 2=controladora · 3=coligada · 4=matriz · 5=filial ou sucursal · 6=outro · 9=desconhecido. Não existe 7 nem 8."},"moeda":{"type":"string","nullable":true,"description":"<tpMoeda> — código de 3 dígitos da tabela do BACEN, NÃO o ISO 4217: dólar americano é 220 (não 840) e euro é 978. Os dois casam com [0-9]{3}, então o código errado sai AUTORIZADO declarando outra moeda."},"valorNaMoeda":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true,"description":"<vServMoeda> — valor do serviço NA MOEDA ESTRANGEIRA, não em reais. É o único campo do grupo sem padrão na empresa: varia a cada operação."},"mecanismoPrestador":{"type":"string","nullable":true,"description":"<mecAFComexP> — mecanismo de apoio ao comércio exterior do PRESTADOR (00 a 08)."},"mecanismoTomador":{"type":"string","nullable":true,"description":"<mecAFComexT> — mecanismo do TOMADOR (00 a 26). Tabela DIFERENTE da do prestador apesar do nome parecido: só 00 e 01 coincidem."},"movimentacaoTemporaria":{"type":"string","nullable":true,"description":"<movTempBens> — 0=desconhecido · 1=não · 2=vinculada a DI · 3=vinculada a DE."},"enviarAoMdic":{"type":"string","nullable":true,"description":"<mdic> — 0=não compartilhar · 1=compartilhar com o MDIC."},"numeroDi":{"type":"string","nullable":true,"description":"<nDI> — número da Declaração de Importação (opcional)."},"numeroRe":{"type":"string","nullable":true,"description":"<nRE> — número do Registro de Exportação (opcional)."}},"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS (NFS-e do Padrão Nacional) — comércio exterior de serviço. Override DESTA nota sobre o padrão da empresa (Configurações → NFS-e), campo a campo: o que vier vazio herda. Os OITO primeiros campos saem juntos no XML ou não sai nenhum — faltando qualquer um (na nota e na empresa), a nota é emitida SEM o grupo, porque meia sequência é recusada pelo esquema. Só vale para os municípios do Padrão Nacional."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador (grupo <infIntermed>) — o marketplace em que a venda aconteceu. Anda JUNTO com `intermediarySellerId`: um sem o outro é recusado com 422. Omita nos dois em venda direta. Quando a nota vem de uma integração, o default é o cadastrado nela."},"intermediarySellerId":{"type":"string","nullable":true,"description":"<idCadIntTran> — identificação do VENDEDOR dentro do marketplace (2 a 60 caracteres)."},"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)"},"nbsCode":{"type":"string","nullable":true,"description":"Código NBS (`<cNBS>`, 9 dígitos; pontos são normalizados). Sem valor, herda do produto e depois do padrão da empresa."},"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"},"freightValue":{"type":"number","minimum":0,"nullable":true,"description":"<vFrete> do PRÓPRIO item (R$). Soma-se ao rateio do frete da nota. Entra no total da nota e na base do ICMS/ST."},"insuranceValue":{"type":"number","minimum":0,"nullable":true,"description":"<vSeg> do item (R$). Entra no total da nota."},"otherValue":{"type":"number","minimum":0,"nullable":true,"description":"<vOutro> — outras despesas acessórias do item (R$). Entra no total da nota."},"discountValue":{"type":"number","minimum":0,"nullable":true,"description":"<vDesc> do PRÓPRIO item (R$). Soma-se ao rateio do desconto da nota e é abatido do total."},"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},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — CST 20/70. A nota prevalece: preenchido, vence o produto e a regra."},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST (4 = MVA, 6 = valor da operação). A nota prevalece: preenchida, vence o produto e a regra."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%). A nota prevalece sobre produto e regra."},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%). A nota prevalece sobre produto e regra."},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota do ICMS-ST no destino (%). A nota prevalece sobre produto e regra."},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — CSOSN 101/201. A nota prevalece sobre produto e regra."},"batches":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string","minLength":1,"description":"<nLote> — até 20 caracteres."},"quantity":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"<qLote> — 3 casas."},"producedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"<dFab> — AAAA-MM-DD, sem hora."},"expiresAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"<dVal> — AAAA-MM-DD. Informe o último dia do mês quando a validade não especifica o dia."},"aggregationCode":{"type":"string","nullable":true,"description":"<cAgreg>."}},"required":["batch","quantity","producedAt","expiresAt"],"additionalProperties":false},"maxItems":500,"nullable":true,"description":"<rastro> — os LOTES deste item. Obrigatório para alimentos, bebidas, medicamentos e defensivos: é o que permite o recall e a conferência de validade na entrada. 🔴 São vários porque a mesma linha da nota pode cobrir quantidade que saiu de mais de um lote; a soma dos `quantity` é a quantidade do item. Lote sem número, sem quantidade ou com data fora de AAAA-MM-DD é DESCARTADO — meia sequence reprovaria o schema de uma nota que, sem o grupo, sairia."},"purchaseOrder":{"type":"string","nullable":true,"description":"<xPed> — pedido de compra DESTE item (até 15 caracteres; o que passar é truncado, não recusado). Cliente B2B confere a nota contra o pedido antes de pagar."},"purchaseOrderItem":{"type":"string","nullable":true,"description":"<nItemPed> — a linha do pedido (até 6 dígitos). Valor fora do formato é DESCARTADO: um número truncado apontaria para a linha errada do pedido, que é pior que não apontar para nenhuma."},"icmsDesonValue":{"type":"number","minimum":0,"nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90. Omitido, é CALCULADO a partir da alíquota: imposto cheio nos CST sem destaque, e a diferença contra a base cheia nos CST 20 e 70."},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS). 🔴 A tabela aceita valores DIFERENTES por CST: 3/9/10/11/12 no 20; 6/7/9 no 30; 1/3/4/5/6/7/8/9/10/11/16/90 no 40, 41 e 50; 3/9/12 no 70 e no 90. Motivo fora da tabela do CST é recusado com 422."},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — quando verdadeiro, o valor desonerado ABATE o total da nota (vNF). Ausente vale como falso, que é o comportamento de toda nota emitida até aqui."},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51. Só ele é enviado: vICMSOp, vICMSDif e vICMS são calculados a partir da base e da alíquota. 100 é o caso comum (diferimento integral) e resulta em vICMS 0,00 — que é diferente de isenção."},"icmsStRetBase":{"type":"number","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$). A nota prevalece sobre o produto."},"icmsStRetRate":{"type":"number","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %). A nota prevalece sobre o produto."},"icmsSubstitutoValue":{"type":"number","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional. A nota prevalece sobre o produto."},"icmsStRetValue":{"type":"number","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$). A nota prevalece sobre o produto."},"fcpStRetBase":{"type":"number","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$). A nota prevalece sobre o produto."},"fcpStRetRate":{"type":"number","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %). A nota prevalece sobre o produto."},"fcpStRetValue":{"type":"number","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$). A nota prevalece sobre o produto."},"cest":{"type":"string","nullable":true,"description":"CEST do item (7 dígitos, pontos opcionais). Vazio = o do produto (`productId`), resolvido na emissão. Exigido quando o ICMS tem ST."},"productId":{"type":"string","nullable":true,"description":"ID de um produto desta empresa (GET /v1/products). Liga o item ao cadastro: a tributação própria do produto e o CEST dele passam a valer, e NCM/CFOP ausentes vêm do produto. Produto de outra empresa é RECUSADO com 422 `invalid_product`."},"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 e a regra do produto. Os campos de imposto explícitos acima têm prioridade sobre ela."},"rtcCClassTrib":{"type":"string","pattern":"^\\d{6}$","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos) deste item. Vazio = resolvido pela hierarquia na emissão (regra do produto → produto → template → empresa). O código é conferido contra a tabela oficial: existência, vigência e modelo. Código fora dela é ACEITO (pode ser de publicação mais nova) — a SEFAZ não rejeita código inexistente, e o erro só apareceria na apuração."},"rtcCst":{"type":"string","pattern":"^\\d{3}$","nullable":true,"description":"CST do IBS/CBS. Deixe vazio: são os 3 primeiros dígitos do `rtcCClassTrib`, e o sistema o deriva. Informar os dois com valores divergentes é RECUSADO — seria uma combinação que não existe."},"rtcAjusteIbs":{"type":"number","nullable":true,"description":"Valor de IBS do grupo de ajuste (gTransfCred no CST 800, gAjusteCompet no 811). DECLARADO, não calculado — esses CST não têm base nem alíquota. Exige `rtcAjusteCbs` junto: o grupo é tudo-ou-nada, e zero é um valor válido."},"rtcAjusteCbs":{"type":"number","nullable":true,"description":"Valor de CBS do grupo de ajuste. Ver `rtcAjusteIbs`."},"rtcEstornoIbs":{"type":"number","nullable":true,"description":"vIBSEstCred do grupo gEstornoCred, exigido pelo indicador do cClassTrib. Exige `rtcEstornoCbs` junto."},"rtcEstornoCbs":{"type":"number","nullable":true,"description":"vCBSEstCred do grupo gEstornoCred. Ver `rtcEstornoIbs`."},"rtcCompetApur":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","nullable":true,"description":"Competência do período de apuração (AAAA-MM, a partir de 2025-01). Exigida por gAjusteCompet (CST 811) e gCredPresIBSZFM (810)."},"rtcZfmTipo":{"type":"string","enum":["0","1","2","3","4"],"nullable":true,"description":"tpCredPresIBSZFM — classificação do art. 450 §1º da LC 214/25, exigida pelo CST 810."},"rtcZfmValor":{"type":"number","nullable":true,"description":"vCredPresIBSZFM — valor do crédito presumido da ZFM (CST 810)."},"rtcCredPresCodigo":{"type":"string","pattern":"^\\d{1,2}$","nullable":true,"description":"cCredPres — código do crédito presumido da OPERAÇÃO (gCredPresOper), da tabela publicada no IT RT 2025.002. Exigido quando o cClassTrib pede o grupo (ex.: 000003, 410014). Código fora da tabela é aceito com AVISO na emissão — a tabela muda por informe técnico."},"rtcCredPresBase":{"type":"number","minimum":0,"nullable":true,"description":"vBCCredPres — base de cálculo do crédito presumido. Obrigatória com o código."},"rtcCredPresIbsPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":100,"nullable":true,"description":"pCredPres do IBS (gIBSCredPres), quando o EMITENTE aproveita o crédito. Sem `rtcCredPresIbsValor`, o valor sai da conta base × percentual."},"rtcCredPresIbsValor":{"type":"number","minimum":0,"nullable":true,"description":"Valor do crédito presumido do IBS. Exige `rtcCredPresIbsPct`."},"rtcCredPresCbsPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":100,"nullable":true,"description":"pCredPres da CBS (gCBSCredPres). Ver `rtcCredPresIbsPct`."},"rtcCredPresCbsValor":{"type":"number","minimum":0,"nullable":true,"description":"Valor do crédito presumido da CBS. Exige `rtcCredPresCbsPct`."},"rtcCredPresCondSus":{"type":"boolean","nullable":true,"description":"Crédito sob condição suspensiva: os valores saem em vCredPresCondSus em vez de vCredPres."},"rtcRefChave":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos) do documento cujo ITEM este ajusta (det/DFeReferenciado). É distinto do `referencedAccessKey` do documento, que referencia a nota inteira: numa nota de crédito que corrige 3 itens de uma venda de 30, só este responde qual linha. Chave malformada é IGNORADA, nunca enviada."},"rtcRefItem":{"type":"integer","minimum":1,"maximum":990,"nullable":true,"description":"Número do item no documento referenciado (nItem). Opcional — sem ele o ajuste aponta o documento, não a linha."}},"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","FOOD_VOUCHER","MEAL_VOUCHER","GIFT_CARD","FUEL_VOUCHER","BANK_DEPOSIT","DIGITAL_WALLET","PIX_STATIC","CASHBACK","PIX_AUTOMATIC","TEF_TRANSFER","LATER_PAYMENT"],"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"},"paidAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true,"description":"<dPag> — a data em que o pagamento OCORREU (AAAA-MM-DD), que pode não ser a da emissão."},"payerCnpj":{"type":"string","nullable":true,"description":"<CNPJPag> — CNPJ do estabelecimento onde o pagamento foi processado, quando é OUTRO que não o emitente (rede de lojas com credenciamento centralizado). 🔴 Sai JUNTO com `payerState`: é uma sequence no leiaute, e só um dos dois faz os DOIS serem descartados na emissão."},"payerState":{"type":"string","minLength":2,"maxLength":2,"nullable":true,"description":"<UFPag> — a UF daquele estabelecimento. Anda com `payerCnpj`."},"receiverCnpj":{"type":"string","nullable":true,"description":"<CNPJReceb> — CNPJ de quem RECEBEU o pagamento."},"terminalId":{"type":"string","nullable":true,"description":"<idTermPag> — identificador do terminal (POS) usado."}},"required":["method","value"],"additionalProperties":false}},"duplicates":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","nullable":true,"description":"Número da parcela (<nDup>). Gerado como \"001\", \"002\"… se omitido."},"dueDate":{"type":"string","description":"Vencimento (<dVenc>) no formato AAAA-MM-DD. Data pura, sem hora."},"value":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Valor da parcela (<vDup>)."}},"required":["dueDate","value"],"additionalProperties":false},"description":"Parcelas da cobrança (grupo <cobr> da NF-e). Presença indica venda a prazo: o XML sai com indPag=1 e a DANFE ganha o bloco FATURA/DUPLICATAS. A SOMA DAS PARCELAS PRECISA FECHAR EXATAMENTE com o total do documento — diferença de um centavo é recusada com 400. Omita em venda à vista."},"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."},"templateId":{"type":"string","nullable":true,"description":"ID de um template fiscal (GET /v1/fiscal-templates) a aplicar na venda. Pré-preenche natureza da operação, CFOP/ICMS (NF-e) ou código de serviço (NFS-e) — só nos campos que você NÃO enviou (fill-empty). Valores explícitos no item/documento têm prioridade."},"transport":{"type":"object","properties":{"freightType":{"type":"string","enum":["SENDER","RECIPIENT","THIRD_PARTY","OWN_SENDER","OWN_RECIPIENT","NO_FREIGHT"],"description":"modFrete — quem paga o frete: SENDER=0 (emitente), RECIPIENT=1 (destinatário), THIRD_PARTY=2 (terceiros), OWN_SENDER=3 e OWN_RECIPIENT=4 (transporte próprio), NO_FREIGHT=9 (sem transporte, default)."},"freightValue":{"type":"number","minimum":0,"description":"Valor do frete (<vFrete>). Entra no total da nota."},"carrierId":{"type":"string","nullable":true,"description":"ID de uma transportadora desta empresa (GET /v1/carriers). Transportadora de outra empresa é RECUSADA com 422 — não descartada em silêncio."},"vehiclePlate":{"type":"string","nullable":true,"description":"Placa DESTA viagem, normalizada para o formato do XSD. Vazio usa o veículo padrão da frota da transportadora."},"vehicleState":{"type":"string","nullable":true,"description":"UF do veículo. OBRIGATÓRIA quando `vehiclePlate` é informada, na MESMA requisição: o <UF> do <veicTransp> é enumerado no XSD e placa sem UF seria rejeição 215 na emissão."},"vehicleRntc":{"type":"string","nullable":true,"description":"RNTC do veículo (ANTT)"},"volumeQuantity":{"type":"integer","minimum":0,"nullable":true,"description":"Quantidade de volumes (<qVol>)"},"volumeSpecies":{"type":"string","nullable":true,"description":"Espécie dos volumes (<esp>): CAIXA, PALETE, SACO..."},"volumeBrand":{"type":"string","nullable":true,"description":"Marca dos volumes (<marca>)"},"volumeNumbering":{"type":"string","nullable":true,"description":"Numeração dos volumes (<nVol>)"},"volumeGrossWeight":{"type":"number","minimum":0,"nullable":true,"description":"Peso bruto em kg (<pesoB>)"},"volumeNetWeight":{"type":"number","minimum":0,"nullable":true,"description":"Peso líquido em kg (<pesoL>)"}},"additionalProperties":false,"nullable":true,"description":"Grupo X (<transp>) da NF-e — transportadora, veículo e volumes. É o que preenche o quadro TRANSPORTADOR / VOLUMES TRANSPORTADOS da DANFE. Omita em venda sem transporte (serviço, digital, retirada em mãos): a nota sai exatamente como sempre saiu. NFS-e não tem esse grupo."},"discountValue":{"type":"number","minimum":0,"nullable":true,"description":"Desconto INCONDICIONAL da nota. É rateado entre os itens (`det/prod/vDesc`) e ABATE a base do imposto — não é só um abatimento do total. Desconto condicional (por antecipação de pagamento) não entra aqui: ele não reduz a base."},"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."},"rtcCreditType":{"type":"string","enum":["01","02","03","04","05"],"nullable":true,"description":"Nota de CRÉDITO da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo codificado: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização do destinatário; 04=redução de valores; 05=transferência de crédito na sucessão. Só NF-e (modelo 55); a nota sai sem cobrança (tPag=90). Mutuamente exclusivo com rtcDebitType."},"rtcDebitType":{"type":"string","enum":["01","02","03","04","05","06","07","08"],"nullable":true,"description":"Nota de DÉBITO da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo codificado: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples Nacional. Só NF-e (modelo 55); a nota sai sem cobrança (tPag=90). Mutuamente exclusivo com rtcCreditType."},"isDevolution":{"type":"boolean","nullable":true,"description":"Nota de DEVOLUÇÃO (finNFe=4). O tipo da operação (entrada ou saída) NÃO vem daqui: sai da faixa do CFOP dos itens — 1xxx/2xxx é entrada (cliente devolvendo a você), 5xxx/6xxx é saída (você devolvendo ao fornecedor). Mutuamente exclusiva com as notas de crédito/débito da RTC. Informe também `referencedAccessKey`: com ela, o IPI devolvido de cada item é lido do XML da nota original e sai no grupo <impostoDevol>; sem ela, ou se a chave não achar a nota, a devolução é criada sem esse grupo (ele é opcional no leiaute)."},"referencedAccessKey":{"type":"string","pattern":"^\\d{44}$","nullable":true,"description":"Chave de acesso (44 dígitos) da NF-e original ajustada ou devolvida — vira <refNFe> na emissão. Recomendado nas notas de crédito/débito, e é o que destrava o <impostoDevol> na devolução."},"fiscalPurpose":{"type":"string","enum":["COMPLEMENTAR","AJUSTE"],"nullable":true,"description":"Finalidade da nota (B1). COMPLEMENTAR = finNFe 2, para corrigir valor ou imposto declarado A MENOS numa nota já autorizada (a complementar carrega só a DIFERENÇA). AJUSTE = finNFe 3. 🔴 Mutuamente exclusiva com `isDevolution` e com as notas de crédito/débito — a nota tem UMA finalidade. As duas EXIGEM o documento referenciado (`referencedAccessKey` ou `references`)."},"places":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["PICKUP","DELIVERY"],"description":"PICKUP = <retirada> (de onde a mercadoria SAI) · DELIVERY = <entrega> (para onde ela VAI). Um de cada, no máximo."},"cnpj":{"type":"string","nullable":true,"description":"CNPJ de quem retira/recebe — OU o CPF."},"cpf":{"type":"string","nullable":true,"description":"CPF de quem retira/recebe — OU o CNPJ."},"name":{"type":"string","nullable":true,"description":"Nome/razão social do local."},"street":{"type":"string","minLength":1,"description":"Logradouro (xLgr)."},"number":{"type":"string","minLength":1,"description":"Número (nro)."},"complement":{"type":"string","nullable":true,"description":"Complemento (xCpl)."},"neighborhood":{"type":"string","minLength":1,"description":"Bairro (xBairro)."},"cityCode":{"type":"string","minLength":1,"description":"Código IBGE do município (cMun)."},"cityName":{"type":"string","minLength":1,"description":"Nome do município (xMun)."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"UF."},"zipCode":{"type":"string","nullable":true,"description":"CEP."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (cPais)."},"countryName":{"type":"string","nullable":true,"description":"Nome do país (xPais)."},"phone":{"type":"string","nullable":true,"description":"Telefone."},"email":{"type":"string","nullable":true,"description":"E-mail."},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual de quem retira/recebe."}},"required":["kind","street","number","neighborhood","cityCode","cityName","state"],"additionalProperties":false},"maxItems":2,"nullable":true,"description":"Local de RETIRADA e de ENTREGA (<retirada>/<entrega>), quando diferentes do remetente e do destinatário — e-commerce com entrega em outro endereço, dropshipping, venda à ordem. Um de cada `kind`; o segundo com o mesmo kind é descartado."},"competence":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","nullable":true,"description":"NFS-e: competência do serviço (<dCompet>), em AAAA-MM ou AAAA-MM-DD. Ausente = a data de emissão, que é o comportamento de toda nota. Serve a quem fatura no mês seguinte ao serviço — mensalidade, contador, manutenção."},"serviceMunicipalityCode":{"type":"string","nullable":true,"description":"NFS-e: código IBGE do município onde o serviço foi PRESTADO, quando diferente do que a Regra Fiscal resolveria. 🔴 Serviço em obra, em evento ou na sede do cliente ficava declarado no município da empresa, e o ISS vai para a prefeitura errada — o que não volta como rejeição, volta na fiscalização."},"serviceDeductionValue":{"type":"number","minimum":0,"nullable":true,"description":"NFS-e: dedução/redução da base em VALOR (<vDR> do <vDedRed>). 🔴 VENCE o percentual da Regra Fiscal: agência de viagem, turismo e construção civil deduzem o repasse ao fornecedor e o material aplicado, que mudam a cada nota e não cabem numa alíquota de cadastro. O grupo é um `xs:choice` — percentual e valor nunca saem juntos."},"construction":{"type":"object","properties":{"registration":{"type":"string","nullable":true,"description":"Inscrição imobiliária fiscal (IPTU). NÃO identifica a obra."},"code":{"type":"string","nullable":true,"description":"Código CNO/CEI da obra (`<cObra>`)."},"cib":{"type":"string","nullable":true,"description":"Código CIB (`<cCIB>`). Só no Padrão Nacional."},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Endereço da obra. Só no Padrão Nacional; vai inteiro."},"techDoc":{"type":"string","nullable":true,"description":"Documento técnico: ART, RRT ou DRT. Vai no `<idDocTec>` do `<infoCompl>` no Padrão Nacional e no `<Art>` do `<ConstrucaoCivil>` no ABRASF."}},"additionalProperties":false,"nullable":true,"description":"NFS-e de construção civil (LC 7.02 e 7.05). 🔴 A identificação da obra é um `xs:choice`: informe UM e só um entre `code` (CNO/CEI), `cib` e o endereço. A inscrição imobiliária é opcional e fica FORA da escolha — ela não identifica a obra sozinha."},"substitutedDocumentId":{"type":"string","nullable":true,"description":"NFS-e: id da nota que esta SUBSTITUI. 🔴 A substituição é UMA operação, não 'cancela e emite': o grupo <subst> vai na DPS desta nota e quem cancela a antiga é a Sefin (ou, no ABRASF, o próprio SubstituirNfse). A nota indicada precisa ser uma NFS-e AUTORIZADA desta empresa, com chave de acesso."},"substitutionReason":{"type":"string","nullable":true,"description":"Código de justificativa da substituição (TSCodJustSubst): 01 desenquadramento do Simples, 02 enquadramento, 03 inclusão retroativa de imunidade, 04 exclusão retroativa, 05 rejeição pelo tomador, 99 outros. Vazio = 99. 🔴 NÃO é a tabela do cancelamento comum (1/2/9), que tem o mesmo nome de campo."},"substitutionNote":{"type":"string","nullable":true,"description":"Texto do motivo da substituição (<xMotivo>, opcional). Mínimo de 15 caracteres no schema — texto curto é completado com o rótulo do código em vez de reprovar."},"serviceFinalUse":{"type":"boolean","nullable":true,"description":"NFS-e: <indFinal> da DPS — operação de uso ou consumo PESSOAL de sócio ou administrador (art. 57 da LC 214/2025). 🔴 NÃO é o consumidor final da NF-e e não se deriva do cliente: aquele diz que o comprador é o fim da cadeia, este diz para que o serviço foi. Ausente = não."},"purchaseNote":{"type":"string","nullable":true,"description":"<xNEmp> — nota de EMPENHO. É o que o órgão público exige na nota para liquidar o pagamento."},"purchaseOrderRef":{"type":"string","nullable":true,"description":"<xPed> do grupo <compra> — o pedido de compra da NOTA INTEIRA. 🔴 Não confundir com o `purchaseOrder` do ITEM: os dois existem no leiaute e não são o mesmo campo."},"purchaseContract":{"type":"string","nullable":true,"description":"<xCont> — número do contrato de compra."},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["NFE","NF_PAPEL","NF_PRODUTOR","CTE","ECF"],"description":"NFE = NF-e por chave · NF_PAPEL = nota em papel modelo 1/1A · NF_PRODUTOR = nota fiscal de produtor rural · CTE = conhecimento de transporte por chave · ECF = cupom fiscal"},"accessKey":{"type":"string","nullable":true,"description":"NFE e CTE: chave de acesso, 44 dígitos."},"stateCode":{"type":"string","nullable":true,"description":"NF_PAPEL e NF_PRODUTOR: código IBGE da UF do emitente (cUF)."},"yearMonth":{"type":"string","nullable":true,"description":"NF_PAPEL e NF_PRODUTOR: ano e mês da emissão (AAMM)."},"cnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente referenciado."},"cpf":{"type":"string","nullable":true,"description":"NF_PRODUTOR: CPF do produtor — OU o CNPJ, nunca os dois."},"stateRegistration":{"type":"string","nullable":true,"description":"NF_PRODUTOR: inscrição estadual do produtor (obrigatória)."},"model":{"type":"string","nullable":true,"description":"NF_PAPEL: 01 ou 02 · NF_PRODUTOR: 01 ou 04 · ECF: 2B, 2C ou 2D."},"series":{"type":"string","nullable":true,"description":"Série do documento (0 a 889)."},"number":{"type":"string","nullable":true,"description":"Número do documento."},"ecfNumber":{"type":"string","nullable":true,"description":"ECF: número de ordem do equipamento (nECF)."},"cooNumber":{"type":"string","nullable":true,"description":"ECF: contador de ordem de operação (nCOO)."}},"required":["kind"],"additionalProperties":false},"maxItems":999,"nullable":true,"description":"Documentos referenciados (<NFref>). Até 999, e UM tipo por item — o leiaute declara um `xs:choice`, então referenciar uma NF-e e um cupom são DOIS itens. Além da NF-e por chave, cobre a nota em PAPEL (modelo 1/1A), a nota de PRODUTOR RURAL, o CT-e e o CUPOM FISCAL. O `referencedAccessKey` continua valendo e é somado a esta lista, sem duplicar."}},"required":["type","items"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"Chave de idempotência da criação (1–100 caracteres `[A-Za-z0-9_.:-]`). Repetir a chave com o mesmo corpo devolve a nota da primeira chamada."},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Repetição de uma criação com a mesma `Idempotency-Key` e o mesmo corpo: a nota que já existe","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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev (presente quando emit=true)"},"precheckErrors":{"type":"array","items":{"type":"string"},"description":"Presente quando `emit=true` mas a pré-validação de configuração reprovou: o rascunho FOI criado (por isso 201) e a emissão NÃO foi disparada. Corrija o que está listado aqui e chame POST /fiscal-documents/{id}/emit."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","runId"],"additionalProperties":false,"description":"Repetição de uma criação com a mesma `Idempotency-Key` e o mesmo corpo: a nota que já existe"}}}},"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev (presente quando emit=true)"},"precheckErrors":{"type":"array","items":{"type":"string"},"description":"Presente quando `emit=true` mas a pré-validação de configuração reprovou: o rascunho FOI criado (por isso 201) e a emissão NÃO foi disparada. Corrija o que está listado aqui e chame POST /fiscal-documents/{id}/emit."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","runId"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/emit":{"post":{"summary":"Dispara a emissão de um documento fiscal (assíncrono)","tags":["Accounting"],"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. Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","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":"companyId","required":true},{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}":{"get":{"summary":"Detalha um documento fiscal pelo id","tags":["Accounting"],"description":"Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo).","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"fiscalPurpose":{"type":"string","nullable":true,"description":"<finNFe> 2/3 (COMPLEMENTAR/AJUSTE); null = normal"},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"accessKey":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"yearMonth":{"type":"string","nullable":true},"cnpj":{"type":"string","nullable":true},"cpf":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"series":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"ecfNumber":{"type":"string","nullable":true},"cooNumber":{"type":"string","nullable":true}},"required":["kind","accessKey","stateCode","yearMonth","cnpj","cpf","stateRegistration","model","series","number","ecfNumber","cooNumber"],"additionalProperties":false},"description":"<NFref> — documentos referenciados"},"places":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"<retirada>/<entrega> — `kind` PICKUP | DELIVERY"},"purchase":{"type":"object","properties":{"note":{"type":"string","nullable":true,"description":"<xNEmp>"},"orderRef":{"type":"string","nullable":true,"description":"<xPed>"},"contract":{"type":"string","nullable":true,"description":"<xCont>"}},"required":["note","orderRef","contract"],"additionalProperties":false,"nullable":true},"competence":{"type":"string","nullable":true,"description":"NFS-e: AAAA-MM-DD; null = data de emissão"},"serviceMunicipalityCode":{"type":"string","nullable":true},"serviceFinalUse":{"type":"boolean","nullable":true},"serviceDeductionValue":{"type":"string","nullable":true},"construction":{"type":"object","properties":{"registration":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"cib":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"techDoc":{"type":"string","nullable":true}},"required":["registration","code","cib","zipCode","street","number","complement","neighborhood","techDoc"],"additionalProperties":false,"nullable":true},"substitution":{"type":"object","properties":{"substitutedDocumentId":{"type":"string"},"reason":{"type":"string","nullable":true},"note":{"type":"string","nullable":true}},"required":["substitutedDocumentId","reason","note"],"additionalProperties":false,"nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer"},"productId":{"type":"string","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true},"cfop":{"type":"string"},"unit":{"type":"string"},"quantity":{"type":"string"},"unitValue":{"type":"string"},"totalValue":{"type":"string"},"discountValue":{"type":"string","nullable":true},"freightValue":{"type":"string","nullable":true},"insuranceValue":{"type":"string","nullable":true},"otherValue":{"type":"string","nullable":true},"nbsCode":{"type":"string","nullable":true,"description":"<cNBS> do item (NFS-e)"},"purchaseOrder":{"type":"string","nullable":true,"description":"<xPed> do item"},"purchaseOrderItem":{"type":"string","nullable":true,"description":"<nItemPed> do item"},"icms":{"type":"object","properties":{"origin":{"type":"string","nullable":true},"situation":{"type":"string","nullable":true,"description":"CST ou CSOSN"},"rate":{"type":"string","nullable":true},"desonerationValue":{"type":"string","nullable":true},"desonerationReason":{"type":"string","nullable":true},"desonerationDeduct":{"type":"boolean","nullable":true},"deferralRate":{"type":"string","nullable":true},"stRetainedBase":{"type":"string","nullable":true},"stRetainedRate":{"type":"string","nullable":true},"substituteValue":{"type":"string","nullable":true},"stRetainedValue":{"type":"string","nullable":true},"fcpStRetainedBase":{"type":"string","nullable":true},"fcpStRetainedRate":{"type":"string","nullable":true},"fcpStRetainedValue":{"type":"string","nullable":true}},"required":["origin","situation","rate","desonerationValue","desonerationReason","desonerationDeduct","deferralRate","stRetainedBase","stRetainedRate","substituteValue","stRetainedValue","fcpStRetainedBase","fcpStRetainedRate","fcpStRetainedValue"],"additionalProperties":false},"ibsCbs":{"type":"object","properties":{"cst":{"type":"string","nullable":true},"cClassTrib":{"type":"string","nullable":true},"amounts":{"type":"object","properties":{"taxBase":{"type":"string","nullable":true,"description":"vBC do gIBSCBS"},"ibsStateRate":{"type":"string","nullable":true,"description":"pIBSUF (%)"},"ibsStateValue":{"type":"string","nullable":true,"description":"vIBSUF"},"ibsMunicipalRate":{"type":"string","nullable":true,"description":"pIBSMun (%)"},"ibsMunicipalValue":{"type":"string","nullable":true,"description":"vIBSMun"},"cbsRate":{"type":"string","nullable":true,"description":"pCBS (%)"},"cbsValue":{"type":"string","nullable":true,"description":"vCBS"}},"required":["taxBase","ibsStateRate","ibsStateValue","ibsMunicipalRate","ibsMunicipalValue","cbsRate","cbsValue"],"additionalProperties":false,"nullable":true,"description":"Destaque de IBS/CBS CALCULADO na emissão para esta linha — a soma das linhas fecha com `taxTotals.rtcIbsTotal`/`rtcCbsTotal`. `null` quando a linha não destacou (rascunho, nota sem o grupo, nota de ajuste); nunca um objeto de zeros, que afirmaria destaque zerado."},"adjustment":{"type":"object","properties":{"ibs":{"type":"string","nullable":true},"cbs":{"type":"string","nullable":true}},"required":["ibs","cbs"],"additionalProperties":false,"nullable":true,"description":"Grupo de ajuste DECLARADO (gTransfCred/gAjusteCompet) — o `rtcAjusteIbs`/`rtcAjusteCbs` do POST. `null` quando não há."},"creditReversal":{"type":"object","properties":{"ibs":{"type":"string","nullable":true},"cbs":{"type":"string","nullable":true}},"required":["ibs","cbs"],"additionalProperties":false,"nullable":true,"description":"gEstornoCred — o `rtcEstornoIbs`/`rtcEstornoCbs` do POST."},"assessmentPeriod":{"type":"string","nullable":true,"description":"Competência de apuração (AAAA-MM) — o `rtcCompetApur` do POST."},"zfmPresumedCredit":{"type":"object","properties":{"type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["type","value"],"additionalProperties":false,"nullable":true,"description":"gCredPresIBSZFM — `rtcZfmTipo`/`rtcZfmValor` do POST."},"referencedItem":{"type":"object","properties":{"accessKey":{"type":"string","nullable":true},"item":{"type":"integer","nullable":true}},"required":["accessKey","item"],"additionalProperties":false,"nullable":true,"description":"det/DFeReferenciado — `rtcRefChave`/`rtcRefItem` do POST."},"operationPresumedCredit":{"type":"object","properties":{"code":{"type":"string","nullable":true},"taxBase":{"type":"string","nullable":true},"ibs":{"type":"object","properties":{"rate":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["rate","value"],"additionalProperties":false,"nullable":true},"cbs":{"type":"object","properties":{"rate":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["rate","value"],"additionalProperties":false,"nullable":true},"suspensiveCondition":{"type":"boolean"}},"required":["code","taxBase","ibs","cbs","suspensiveCondition"],"additionalProperties":false,"nullable":true,"description":"gCredPresOper — os `rtcCredPres*` do POST. `null` quando não há."}},"required":["cst","cClassTrib","amounts","adjustment","creditReversal","assessmentPeriod","zfmPresumedCredit","referencedItem","operationPresumedCredit"],"additionalProperties":false},"batches":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string"},"quantity":{"type":"string"},"producedAt":{"type":"string","description":"AAAA-MM-DD"},"expiresAt":{"type":"string","description":"AAAA-MM-DD"},"aggregationCode":{"type":"string","nullable":true}},"required":["batch","quantity","producedAt","expiresAt","aggregationCode"],"additionalProperties":false},"description":"<rastro> — lotes do item"}},"required":["sequence","productId","code","description","ncm","cest","cfop","unit","quantity","unitValue","totalValue","discountValue","freightValue","insuranceValue","otherValue","nbsCode","purchaseOrder","purchaseOrderItem","icms","ibsCbs","batches"],"additionalProperties":false}},"payments":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer"},"method":{"type":"string"},"value":{"type":"string"},"description":{"type":"string","nullable":true},"cardFlag":{"type":"string","nullable":true},"cardCNPJ":{"type":"string","nullable":true},"cardAuthorization":{"type":"string","nullable":true},"pixKey":{"type":"string","nullable":true},"pixTxId":{"type":"string","nullable":true},"paidAt":{"type":"string","nullable":true,"description":"<dPag> — AAAA-MM-DD"},"payerCnpj":{"type":"string","nullable":true},"payerState":{"type":"string","nullable":true},"receiverCnpj":{"type":"string","nullable":true},"terminalId":{"type":"string","nullable":true}},"required":["sequence","method","value","description","cardFlag","cardCNPJ","cardAuthorization","pixKey","pixTxId","paidAt","payerCnpj","payerState","receiverCnpj","terminalId"],"additionalProperties":false}},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"CANCELLATION | CORRECTION | CONFIRMATION | DELIVERY_RECEIPT | DELIVERY_RECEIPT_CANCELLATION | …"},"code":{"type":"string","description":"tpEvento (ex.: 110111, 110130)"},"sequence":{"type":"integer"},"protocol":{"type":"string","nullable":true},"authorized":{"type":"boolean"},"rejectionReason":{"type":"string","nullable":true},"createdAt":{"type":"string"},"delivery":{"type":"object","properties":{"deliveredAt":{"type":"string","nullable":true},"receiverName":{"type":"string","nullable":true},"receiverDocument":{"type":"string","nullable":true},"latitude":{"type":"string","nullable":true},"longitude":{"type":"string","nullable":true},"proofHash":{"type":"string","nullable":true}},"required":["deliveredAt","receiverName","receiverDocument","latitude","longitude","proofHash"],"additionalProperties":false,"nullable":true,"description":"Só no DELIVERY_RECEIPT (110130)"},"referencedProtocol":{"type":"string","nullable":true,"description":"No cancelamento do comprovante (110131): o protocolo que ele cancela"}},"required":["type","code","sequence","protocol","authorized","rejectionReason","createdAt","delivery","referencedProtocol"],"additionalProperties":false}},"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},"duplicates":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"<nDup>"},"dueDate":{"type":"string","description":"<dVenc> — AAAA-MM-DD"},"value":{"type":"string","description":"<vDup> — decimal como string"}},"required":["number","dueDate","value"],"additionalProperties":false},"description":"Parcelas da cobrança. Lista vazia = venda à vista (sem grupo <cobr>)."},"transport":{"type":"object","properties":{"freightType":{"type":"string","nullable":true,"description":"SENDER | RECIPIENT | THIRD_PARTY | OWN_* | NO_FREIGHT"},"freightValue":{"type":"string","description":"Decimal como string"},"carrierId":{"type":"string","nullable":true},"carrierName":{"type":"string","nullable":true,"description":"Snapshot: sobrevive à exclusão da transportadora"},"carrierDocument":{"type":"string","nullable":true,"description":"Snapshot"},"vehiclePlate":{"type":"string","nullable":true},"vehicleState":{"type":"string","nullable":true},"vehicleRntc":{"type":"string","nullable":true},"volumeQuantity":{"type":"integer","nullable":true},"volumeSpecies":{"type":"string","nullable":true},"volumeBrand":{"type":"string","nullable":true},"volumeNumbering":{"type":"string","nullable":true},"volumeGrossWeight":{"type":"string","nullable":true,"description":"kg, decimal como string"},"volumeNetWeight":{"type":"string","nullable":true,"description":"kg, decimal como string"}},"required":["freightType","freightValue","carrierId","carrierName","carrierDocument","vehiclePlate","vehicleState","vehicleRntc","volumeQuantity","volumeSpecies","volumeBrand","volumeNumbering","volumeGrossWeight","volumeNetWeight"],"additionalProperties":false,"nullable":true,"description":"Grupo X (<transp>). null quando a nota não tem transporte."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","fiscalPurpose","references","places","purchase","competence","serviceMunicipalityCode","serviceFinalUse","serviceDeductionValue","construction","substitution","items","payments","events","nfseNumber","verificationCode","protocolNumber","rejectionReason","cancellationReason","cancellationDate","duplicates","transport"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/cancel":{"post":{"summary":"Cancela um documento fiscal autorizado","tags":["Accounting"],"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). Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"justification":{"type":"string","minLength":15,"maxLength":255,"description":"Justificativa do cancelamento (15–255 caracteres)"},"cancellationReason":{"type":"string","enum":["1","2","9"],"nullable":true,"description":"NFS-e (Padrão Nacional): <cMotivo> do evento e101101 — 1 = erro na emissão, 2 = serviço NÃO PRESTADO, 9 = outros. Ausente vale 1. 🔴 São coisas diferentes e a prefeitura lê a diferença: erro de emissão diz que a operação existiu e o documento saiu errado; serviço não prestado diz que a operação não aconteceu. Ignorado na NF-e, cujo evento de cancelamento não tem código de motivo."}},"required":["justification"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/correction-letter":{"post":{"summary":"Emite uma Carta de Correção (CC-e)","tags":["Accounting"],"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. Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","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":"companyId","required":true},{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/delivery-receipt":{"post":{"summary":"Registra o comprovante de entrega da NF-e","tags":["Accounting"],"description":"Registra na SEFAZ (Ambiente Nacional) o evento 110130 — quem recebeu a mercadoria, quando e o hash da imagem do comprovante (canhoto assinado, assinatura, documento). Só NF-e modelo 55 AUTORIZADA. Síncrono. 🔴 Com o comprovante registrado a NF-e NÃO pode ser cancelada (rejeição 826) e não aceita outro comprovante (825): cancele-o antes com `DELETE`. A imagem é guardada pela plataforma; a SEFAZ recebe só o hash. Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deliveredAt":{"type":"string","format":"date-time","description":"Data e hora da entrega, ISO 8601 com fuso. Não pode ser futura nem anterior à emissão."},"receiverName":{"type":"string","minLength":2,"maxLength":60,"description":"Nome de quem recebeu"},"receiverDocument":{"type":"string","minLength":2,"maxLength":20,"description":"Documento de quem recebeu (RG, CPF ou outro)"},"latitude":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"longitude":{"type":"number","minimum":-180,"maximum":180,"nullable":true},"proof":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","application/pdf"]},"base64":{"type":"string","minLength":1,"description":"Arquivo do comprovante em base64 (até 3 MB decodificado)"}},"required":["contentType","base64"],"additionalProperties":false}},"required":["deliveredAt","receiverName","receiverDocument","proof"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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]},"protocol":{"type":"string","description":"Protocolo do evento no Ambiente Nacional"},"sequence":{"type":"integer"}},"required":["success","protocol","sequence"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Cancela o comprovante de entrega ativo da NF-e","tags":["Accounting"],"description":"Envia o evento 110131, que referencia o protocolo do comprovante ativo. Depois dele a NF-e volta a poder ser cancelada e aceita um novo comprovante. Chave do escritório com `documents:write`; a empresa precisa estar na carteira (vínculo ativo) E ter permitido a emissão pelo escritório (`officeIssuingAllowed`; sem isso, 403 `office_issuing_not_allowed`). A nota é da EMPRESA — plano, cota e certificado são os dela — e registra a chave do escritório como emissora.","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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]},"protocol":{"type":"string"},"sequence":{"type":"integer"}},"required":["success","protocol","sequence"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/xml":{"get":{"summary":"Baixa o XML do documento fiscal","tags":["Accounting"],"description":"Retorna o XML autorizado (ou assinado com `?type=signed`). Use `?download=true` para forçar download como anexo. Resposta: `application/xml`. Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo).","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":"companyId","required":true},{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-documents/{id}/danfe":{"get":{"summary":"Baixa a DANFE/DANFSe (PDF) do documento fiscal","tags":["Accounting"],"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`. Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo).","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-templates":{"get":{"summary":"Lista os templates fiscais visíveis pela empresa","tags":["Accounting"],"description":"Retorna os templates da empresa + do tenant + da plataforma (campo `source`). Use o `id` como `templateId` em POST /v1/fiscal-documents. Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo). Só leitura: os templates são geridos pela empresa.","parameters":[{"schema":{"type":"string","enum":["NFE","NFSE"]},"in":"query","name":"type","required":false,"description":"Filtra por modelo (NFE/NFSE)"},{"schema":{"type":"string"},"in":"path","name":"companyId","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"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/fiscal-templates/{id}":{"get":{"summary":"Detalha um template fiscal visível pela empresa","tags":["Accounting"],"description":"Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo). Só leitura: os templates são geridos pela empresa.","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do template"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/nfse-readiness":{"get":{"summary":"A empresa consegue emitir NFS-e agora?","tags":["Accounting"],"description":"Confere, SEM criar rascunho, o que impediria a emissão de uma NFS-e da empresa pela integração: certificado A1, configuração de NFS-e, webservice do município, template de NFS-e, cota do plano e a permissão da empresa para o escritório emitir. `ready` = nenhuma pendência. Cada pendência vem com um `code` estável (`certificate_missing`, `certificate_expired`, `nfse_not_configured`, `municipality_unsupported`, `no_nfse_template`, `quota_exhausted`, `office_issuing_not_allowed`) e uma mensagem em português que diz o que a empresa precisa fazer. Não substitui a pré-validação da emissão, que confere também os dados da nota (serviço, tomador, valores). Chave do escritório com `documents:read`; a empresa precisa estar na carteira (vínculo ativo).","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean","description":"`true` = nenhuma pendência em `issues`"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"certificate_missing · certificate_expired · nfse_not_configured · municipality_unsupported · no_nfse_template · quota_exhausted · office_issuing_not_allowed"},"message":{"type":"string","description":"O que a empresa precisa fazer (pt-BR)"}},"required":["code","message"],"additionalProperties":false}},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"expiresAt":{"type":"string","nullable":true,"description":"Validade do certificado A1 (ISO)"}},"required":["present","expiresAt"],"additionalProperties":false},"templates":{"type":"integer","description":"Templates de NFS-e visíveis pela empresa"},"defaultTemplateId":{"type":"string","nullable":true,"description":"O template de NFS-e marcado como padrão (o da empresa vence o do tenant)"},"officeIssuingAllowed":{"type":"boolean","description":"A empresa permite que o escritório emita pela integração"}},"required":["ready","issues","certificate","templates","defaultTemplateId","officeIssuingAllowed"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/clients":{"get":{"summary":"Lista os clientes da empresa","tags":["Accounting"],"description":"O cadastro de clientes (tomadores/destinatários) da empresa — o `clientId` da criação de nota pela carteira, sem duplicar cadastro. Mesma forma e mesmos filtros de `GET /v1/clients`. Só leitura: o cadastro é gerido pela empresa. Chave do escritório com `clients:read`; a empresa precisa estar na carteira (vínculo ativo).","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":"search","required":false,"description":"Busca por nome, documento, email ou nome fantasia"},{"schema":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"]},"in":"query","name":"documentType","required":false,"description":"Filtra por tipo de documento"},{"schema":{"type":"string"},"in":"query","name":"state","required":false,"description":"Filtra por UF"},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false,"description":"Filtra por ativos/inativos"},{"schema":{"type":"string"},"in":"path","name":"companyId","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"},"type":{"type":"string","description":"INDIVIDUAL | COMPANY | FOREIGN"},"documentType":{"type":"string","description":"CPF | CNPJ | FOREIGN | OTHER"},"document":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>)"},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"countryCode":{"type":"string"},"municipalityCode":{"type":"string","nullable":true},"taxRegime":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","type","documentType","document","name","tradingName","email","phone","mobilePhone","stateRegistration","municipalRegistration","suframaRegistration","zipCode","street","number","complement","neighborhood","city","state","country","countryCode","municipalityCode","taxRegime","isActive","createdAt","updatedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/webhooks":{"get":{"summary":"Lista os webhooks do escritório","tags":["Accounting"],"description":"Endpoints que recebem os eventos de toda a carteira. Exige a chave do escritório com `webhooks:write`.","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","received_document.created","received_document.updated","link.updated"]},"description":"Eventos assinados. Vazio = todos"},"isActive":{"type":"boolean","description":"false = desativado automaticamente por falhas seguidas (`disabledReason`). Para voltar a receber, remova e cadastre de novo."},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cadastra um webhook do escritório","tags":["Accounting"],"description":"O endpoint recebe os eventos de TODAS as empresas da carteira (vínculo ativo no momento do evento). Corpo de cada entrega: `{ \"id\": \"evt_…\", \"type\": \"<evento>\", \"createdAt\": \"<ISO>\", \"officeId\": \"…\", \"companyId\": \"…\", \"data\": { … } }`. Headers: `X-Webhook-Event`, `X-Webhook-Delivery` e `X-Webhook-Signature: t=<unix>,v1=<hex>` — HMAC-SHA256 com o `secret` sobre `<t>.<corpo cru>`. Deduplique pelo `id` do evento (`evt_…`), que se repete nas tentativas de uma mesma entrega. Responda 2xx em até 10s; falhas são retentadas por até 24h, e 5 entregas seguidas com falha desativam o endpoint. Eventos: `document.authorized` · `document.rejected` · `document.cancelled` · `document.inutilized` (notas emitidas pelas empresas da carteira) · `received_document.created` · `received_document.updated` (notas recebidas: distribuição DF-e, XML completo, manifestação) · `link.updated` (vínculo do escritório criado ou com status novo). URL em **https** (`http://localhost` só fora de produção). Até 5 endpoints por escritório. O `secret` aparece só nesta resposta (e na rotação). Não há POST de verificação no cadastro: o primeiro evento já é real.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048,"nullable":true,"description":"URL https que recebe os eventos"},"description":{"type":"string","maxLength":255,"nullable":true},"events":{"type":"array","items":{"type":"string","enum":["document.authorized","document.rejected","document.cancelled","document.inutilized","received_document.created","received_document.updated","link.updated"]},"nullable":true,"description":"Eventos assinados. Omitido/vazio = todos."}},"additionalProperties":false,"nullable":true}]}}}},"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","received_document.created","received_document.updated","link.updated"]},"description":"Eventos assinados. Vazio = todos"},"isActive":{"type":"boolean","description":"false = desativado automaticamente por falhas seguidas (`disabledReason`). Para voltar a receber, remova e cadastre de novo."},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura (`whsec_…`) — exibido apenas nesta resposta. Guarde-o."}},"required":["id","url","description","events","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/webhooks/{id}":{"delete":{"summary":"Remove um webhook do escritório","tags":["Accounting"],"description":"As entregas pendentes para ele deixam de ser tentadas. Exige `webhooks:write`.","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/webhooks/{id}/rotate-secret":{"post":{"summary":"Gera um novo segredo de assinatura para o webhook do escritório","tags":["Accounting"],"description":"O segredo antigo para de valer na hora: as próximas entregas (inclusive as retentativas de eventos anteriores) já saem assinadas com o novo.","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","received_document.created","received_document.updated","link.updated"]},"description":"Eventos assinados. Vazio = todos"},"isActive":{"type":"boolean","description":"false = desativado automaticamente por falhas seguidas (`disabledReason`). Para voltar a receber, remova e cadastre de novo."},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura (`whsec_…`) — exibido apenas nesta resposta. Guarde-o."}},"required":["id","url","description","events","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/links":{"get":{"summary":"Lista os vínculos do escritório","tags":["Accounting"],"description":"Todos os vínculos — pedidos pendentes, ativos (a carteira), recusados e desfeitos —, do mais recente ao mais antigo. Filtre por `status`.","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":["PENDING","ACTIVE","REFUSED","UNLINKED"]},"in":"query","name":"status","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string","description":"Vira `companyId` das rotas por empresa quando o vínculo estiver ACTIVE"},"taxId":{"type":"string","description":"CNPJ/CPF da empresa, só dígitos"},"companyName":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","REFUSED","UNLINKED"]},"requestedBy":{"type":"string","enum":["COMPANY","OFFICE"],"description":"Quem pediu: OFFICE = o escritório (tela ou API); COMPANY = a própria empresa"},"requestedAt":{"type":"string"},"respondedAt":{"type":"string","nullable":true,"description":"Aceite, recusa ou desvinculação (ISO)"}},"required":["id","companyId","taxId","companyName","status","requestedBy","requestedAt","respondedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Pede vínculo a uma empresa pelo CNPJ/CPF","tags":["Accounting"],"description":"O mesmo \"Convidar empresa\" do Painel do Contador: cria um pedido PENDING, os administradores da empresa recebem o convite por e-mail e aceitam (ou recusam) no app — só então ela entra na carteira. Idempotente: vínculo já ACTIVE com o escritório responde **200** com ele; pedido já PENDING também (**200**, sem novo e-mail); pedido novo responde **201**. Empresa sem cadastro no app responde **404** `company_not_found` (o `email` é aceito e hoje não é usado: não há convite por e-mail para empresa sem cadastro); empresa vinculada a OUTRO escritório, **409** `company_already_linked`. Acompanhe o aceite por `GET /v1/accounting/links` ou pelo webhook `link.updated`. Exige `portfolio:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"taxId":{"type":"string","maxLength":32,"nullable":true,"description":"CNPJ ou CPF (com ou sem máscara)"},"email":{"type":"string","format":"email","maxLength":254,"nullable":true,"description":"Reservado para o convite de empresa sem cadastro (hoje não usado)"}},"additionalProperties":false,"nullable":true}]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string","description":"Vira `companyId` das rotas por empresa quando o vínculo estiver ACTIVE"},"taxId":{"type":"string","description":"CNPJ/CPF da empresa, só dígitos"},"companyName":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","REFUSED","UNLINKED"]},"requestedBy":{"type":"string","enum":["COMPANY","OFFICE"],"description":"Quem pediu: OFFICE = o escritório (tela ou API); COMPANY = a própria empresa"},"requestedAt":{"type":"string"},"respondedAt":{"type":"string","nullable":true,"description":"Aceite, recusa ou desvinculação (ISO)"}},"required":["id","companyId","taxId","companyName","status","requestedBy","requestedAt","respondedAt"],"additionalProperties":false}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string","description":"Vira `companyId` das rotas por empresa quando o vínculo estiver ACTIVE"},"taxId":{"type":"string","description":"CNPJ/CPF da empresa, só dígitos"},"companyName":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","REFUSED","UNLINKED"]},"requestedBy":{"type":"string","enum":["COMPANY","OFFICE"],"description":"Quem pediu: OFFICE = o escritório (tela ou API); COMPANY = a própria empresa"},"requestedAt":{"type":"string"},"respondedAt":{"type":"string","nullable":true,"description":"Aceite, recusa ou desvinculação (ISO)"}},"required":["id","companyId","taxId","companyName","status","requestedBy","requestedAt","respondedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/carriers":{"get":{"summary":"Lista as transportadoras da empresa","tags":["Carriers"],"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":"search","required":false,"description":"Busca por nome ou documento"}],"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"},"tradingName":{"type":"string","nullable":true},"documentType":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"anttCode":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"vehicleCount":{"type":"number","description":"Tamanho da frota. Só na LISTAGEM."},"vehicles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","isActive","createdAt","updatedAt"],"additionalProperties":false},"description":"Frota completa. Só no detalhe (GET /carriers/{id})."},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","tradingName","documentType","document","email","phone","stateRegistration","anttCode","zipCode","street","number","complement","neighborhood","city","state","isActive","createdAt","updatedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria uma transportadora","tags":["Carriers"],"description":"Documento duplicado na empresa → 422. Para cadastrar os veículos, use POST /v1/carriers/{id}/vehicles depois de criar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Razão social da transportadora"},"document":{"type":"string","minLength":1,"description":"CNPJ/CPF (só dígitos ou formatado)"},"documentType":{"type":"string","enum":["CNPJ","CPF"],"description":"Tipo do documento. Default: CNPJ."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual — vai no <IE> do <transporta>"},"anttCode":{"type":"string","nullable":true,"description":"Código ANTT (RNTRC) do transportador"},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro — compõe o <xEnder>"},"number":{"type":"string","nullable":true,"description":"Número — compõe o <xEnder>"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true,"description":"Município — vai no <xMun>"},"state":{"type":"string","nullable":true,"description":"UF (2 letras) — vai no <UF>"}},"required":["name","document"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"documentType":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"anttCode":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"vehicleCount":{"type":"number","description":"Tamanho da frota. Só na LISTAGEM."},"vehicles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","isActive","createdAt","updatedAt"],"additionalProperties":false},"description":"Frota completa. Só no detalhe (GET /carriers/{id})."},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","tradingName","documentType","document","email","phone","stateRegistration","anttCode","zipCode","street","number","complement","neighborhood","city","state","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/carriers/{id}":{"get":{"summary":"Detalha uma transportadora (com a frota)","tags":["Carriers"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"documentType":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"anttCode":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"vehicleCount":{"type":"number","description":"Tamanho da frota. Só na LISTAGEM."},"vehicles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","isActive","createdAt","updatedAt"],"additionalProperties":false},"description":"Frota completa. Só no detalhe (GET /carriers/{id})."},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","tradingName","documentType","document","email","phone","stateRegistration","anttCode","zipCode","street","number","complement","neighborhood","city","state","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza uma transportadora","tags":["Carriers"],"description":"Atualiza apenas os campos enviados.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Razão social da transportadora"},"document":{"type":"string","minLength":1,"description":"CNPJ/CPF (só dígitos ou formatado)"},"documentType":{"type":"string","enum":["CNPJ","CPF"],"description":"Tipo do documento. Default: CNPJ."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual — vai no <IE> do <transporta>"},"anttCode":{"type":"string","nullable":true,"description":"Código ANTT (RNTRC) do transportador"},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro — compõe o <xEnder>"},"number":{"type":"string","nullable":true,"description":"Número — compõe o <xEnder>"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true,"description":"Município — vai no <xMun>"},"state":{"type":"string","nullable":true,"description":"UF (2 letras) — vai no <UF>"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"documentType":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"anttCode":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"vehicleCount":{"type":"number","description":"Tamanho da frota. Só na LISTAGEM."},"vehicles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","isActive","createdAt","updatedAt"],"additionalProperties":false},"description":"Frota completa. Só no detalhe (GET /carriers/{id})."},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","tradingName","documentType","document","email","phone","stateRegistration","anttCode","zipCode","street","number","complement","neighborhood","city","state","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Exclui uma transportadora","tags":["Carriers"],"description":"A frota vai junto (cascade). As NOTAS já emitidas não mudam: elas guardam o snapshot do nome/documento e da placa usada.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/carriers/{id}/vehicles":{"get":{"summary":"Lista a frota de uma transportadora","tags":["Carriers"],"description":"O veículo padrão vem primeiro.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Adiciona um veículo à frota","tags":["Carriers"],"description":"A placa é normalizada e precisa ter formato válido (AAA9999 ou AAA9A99). Placa repetida na mesma frota → 422. O primeiro veículo vira o padrão automaticamente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plate":{"type":"string","minLength":1,"description":"Placa. Normalizada para o formato do XSD ([A-Z0-9], até 7): 'ABC-1234' vira 'ABC1234'. Aceita o padrão antigo (AAA9999) e o Mercosul (AAA9A99)."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"UF de licenciamento. OBRIGATÓRIA: o <UF> do <veicTransp> é enumerado no XSD, e veículo sem UF só se revelaria quebrado na emissão (rejeição 215)."},"rntc":{"type":"string","nullable":true,"description":"Registro do veículo na ANTT"},"description":{"type":"string","nullable":true,"description":"Apelido operacional ('Truck baú'). Só para exibição."},"isDefault":{"type":"boolean","description":"Marca como veículo padrão da transportadora (rebaixa o anterior). O PRIMEIRO veículo da frota vira padrão automaticamente."}},"required":["plate","state"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/carriers/{id}/vehicles/{vehicleId}":{"patch":{"summary":"Atualiza um veículo da frota","tags":["Carriers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plate":{"type":"string","minLength":1,"description":"Placa. Normalizada para o formato do XSD ([A-Z0-9], até 7): 'ABC-1234' vira 'ABC1234'. Aceita o padrão antigo (AAA9999) e o Mercosul (AAA9A99)."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"UF de licenciamento. OBRIGATÓRIA: o <UF> do <veicTransp> é enumerado no XSD, e veículo sem UF só se revelaria quebrado na emissão (rejeição 215)."},"rntc":{"type":"string","nullable":true,"description":"Registro do veículo na ANTT"},"description":{"type":"string","nullable":true,"description":"Apelido operacional ('Truck baú'). Só para exibição."},"isDefault":{"type":"boolean","description":"Marca como veículo padrão da transportadora (rebaixa o anterior). O PRIMEIRO veículo da frota vira padrão automaticamente."},"isActive":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"},{"schema":{"type":"string"},"in":"path","name":"vehicleId","required":true,"description":"ID do veículo"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"carrierId":{"type":"string"},"plate":{"type":"string"},"state":{"type":"string","nullable":true},"rntc":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","carrierId","plate","state","rntc","description","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Remove um veículo da frota","tags":["Carriers"],"description":"Remover o veículo padrão promove outro. As notas já emitidas com essa placa não mudam.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da transportadora"},{"schema":{"type":"string"},"in":"path","name":"vehicleId","required":true,"description":"ID do veículo"}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/clients":{"get":{"summary":"Lista os clientes da empresa","tags":["Clients"],"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":"search","required":false,"description":"Busca por nome, documento, email ou nome fantasia"},{"schema":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"]},"in":"query","name":"documentType","required":false,"description":"Filtra por tipo de documento"},{"schema":{"type":"string"},"in":"query","name":"state","required":false,"description":"Filtra por UF"},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false,"description":"Filtra por ativos/inativos"}],"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":"INDIVIDUAL | COMPANY | FOREIGN"},"documentType":{"type":"string","description":"CPF | CNPJ | FOREIGN | OTHER"},"document":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>)"},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"countryCode":{"type":"string"},"municipalityCode":{"type":"string","nullable":true},"taxRegime":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","type","documentType","document","name","tradingName","email","phone","mobilePhone","stateRegistration","municipalRegistration","suframaRegistration","zipCode","street","number","complement","neighborhood","city","state","country","countryCode","municipalityCode","taxRegime","isActive","createdAt","updatedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um cliente","tags":["Clients"],"description":"Cria um cliente na empresa. `type`/`documentType` são inferidos pelo documento quando omitidos. Documento duplicado na empresa → 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome/razão social do cliente"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (só dígitos ou formatado). Pode ser vazio (consumidor final)."},"documentType":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"],"nullable":true,"description":"Tipo do documento. Inferido pelo documento quando omitido."},"type":{"type":"string","enum":["INDIVIDUAL","COMPANY","FOREIGN"],"nullable":true,"description":"Tipo do cliente. Inferido pelo documento quando omitido."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual"},"municipalRegistration":{"type":"string","nullable":true,"description":"Inscrição municipal"},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>) — 8 ou 9 dígitos. Obrigatória nas operações com a Zona Franca de Manaus e as Áreas de Livre Comércio. Valor fora do formato é descartado na emissão, não enviado: ele reprovaria o schema da NF-e."},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro"},"number":{"type":"string","nullable":true,"description":"Número"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true,"description":"UF (2 letras)"},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"country":{"type":"string","nullable":true,"description":"País. Default: Brasil."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (BACEN). Default: 1058 (Brasil)."}},"required":["name"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"INDIVIDUAL | COMPANY | FOREIGN"},"documentType":{"type":"string","description":"CPF | CNPJ | FOREIGN | OTHER"},"document":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>)"},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"countryCode":{"type":"string"},"municipalityCode":{"type":"string","nullable":true},"taxRegime":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","type","documentType","document","name","tradingName","email","phone","mobilePhone","stateRegistration","municipalRegistration","suframaRegistration","zipCode","street","number","complement","neighborhood","city","state","country","countryCode","municipalityCode","taxRegime","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/clients/{id}":{"get":{"summary":"Detalha um cliente","tags":["Clients"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do cliente"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"INDIVIDUAL | COMPANY | FOREIGN"},"documentType":{"type":"string","description":"CPF | CNPJ | FOREIGN | OTHER"},"document":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>)"},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"countryCode":{"type":"string"},"municipalityCode":{"type":"string","nullable":true},"taxRegime":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","type","documentType","document","name","tradingName","email","phone","mobilePhone","stateRegistration","municipalRegistration","suframaRegistration","zipCode","street","number","complement","neighborhood","city","state","country","countryCode","municipalityCode","taxRegime","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza um cliente","tags":["Clients"],"description":"Atualiza apenas os campos enviados.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome/razão social do cliente"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (só dígitos ou formatado). Pode ser vazio (consumidor final)."},"documentType":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"],"nullable":true,"description":"Tipo do documento. Inferido pelo documento quando omitido."},"type":{"type":"string","enum":["INDIVIDUAL","COMPANY","FOREIGN"],"nullable":true,"description":"Tipo do cliente. Inferido pelo documento quando omitido."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual"},"municipalRegistration":{"type":"string","nullable":true,"description":"Inscrição municipal"},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>) — 8 ou 9 dígitos. Obrigatória nas operações com a Zona Franca de Manaus e as Áreas de Livre Comércio. Valor fora do formato é descartado na emissão, não enviado: ele reprovaria o schema da NF-e."},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro"},"number":{"type":"string","nullable":true,"description":"Número"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true,"description":"UF (2 letras)"},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"country":{"type":"string","nullable":true,"description":"País. Default: Brasil."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (BACEN). Default: 1058 (Brasil)."}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do cliente"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"INDIVIDUAL | COMPANY | FOREIGN"},"documentType":{"type":"string","description":"CPF | CNPJ | FOREIGN | OTHER"},"document":{"type":"string"},"name":{"type":"string"},"tradingName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"municipalRegistration":{"type":"string","nullable":true},"suframaRegistration":{"type":"string","nullable":true,"description":"Inscrição na SUFRAMA (<ISUF>)"},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"countryCode":{"type":"string"},"municipalityCode":{"type":"string","nullable":true},"taxRegime":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","type","documentType","document","name","tradingName","email","phone","mobilePhone","stateRegistration","municipalRegistration","suframaRegistration","zipCode","street","number","complement","neighborhood","city","state","country","countryCode","municipalityCode","taxRegime","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Remove um cliente","tags":["Clients"],"description":"Remove o cliente. Falha com 409 se ele já tiver documentos fiscais vinculados (nesse caso, mantenha o cadastro para preservar o histórico).","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do cliente"}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/company":{"get":{"summary":"Dados da empresa dona da credencial","tags":["Company"],"description":"Retorna a empresa vinculada à chave de API / token OAuth usado. Permite confirmar qual empresa a credencial representa.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Razão social"},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"taxId":{"type":"string","description":"CNPJ"},"email":{"type":"string","nullable":true},"status":{"type":"string","description":"Status cadastral da empresa"},"isActive":{"type":"boolean"},"crtCode":{"type":"string","nullable":true,"description":"Código do Regime Tributário (CRT)"},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição Estadual"},"isStateRegistrationExempt":{"type":"boolean"},"municipalRegistration":{"type":"string","nullable":true,"description":"Inscrição Municipal"},"phone":{"type":"string","nullable":true},"mobile":{"type":"string","nullable":true},"address":{"type":"object","properties":{"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"}},"required":["zipCode","street","number","complement","neighborhood","city","state","municipalityCode"],"additionalProperties":false},"createdAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","tradingName","taxId","email","status","isActive","crtCode","stateRegistration","isStateRegistrationExempt","municipalRegistration","phone","mobile","address","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents":{"get":{"summary":"Lista documentos fiscais da empresa","tags":["Fiscal Documents"],"description":"Ordenadas pela emissão, da mais recente. **Sincronização:** com `changedSince` (ou `cursor`) a lista vira a das notas CRIADAS OU ALTERADAS desde aquele instante — autorização, rejeição, cancelamento, CC-e —, em ordem de alteração, e `page` é ignorado: siga `meta.nextCursor` enquanto `meta.hasMore` for verdadeiro e GUARDE o último `nextCursor` — ele é o marco da próxima rodada (página vazia devolve o mesmo cursor recebido). Os filtros (`status`, `type`, `environment`, `externalId`) valem nos dois modos.","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":["DRAFT","PROCESSING","AUTHORIZED","REJECTED","CANCELLED","DENIED","INUTILIZED"]},"in":"query","name":"status","required":false,"description":"Filtra por status (ex: AUTHORIZED, DRAFT)"},{"schema":{"type":"string","enum":["NFE","NFCE","NFSE"]},"in":"query","name":"type","required":false,"description":"Filtra por tipo (NFE/NFCE/NFSE)"},{"schema":{"type":"string","enum":["PRODUCTION","HOMOLOGATION","ALL"],"default":"PRODUCTION"},"in":"query","name":"environment","required":false,"description":"Ambiente das notas. Padrão PRODUCTION — documento de homologação (teste, sem valor fiscal) só aparece com HOMOLOGATION ou ALL."},{"schema":{"type":"string","maxLength":255},"in":"query","name":"externalId","required":false,"description":"Só as notas com este `externalId` (o id da venda no seu sistema), exato"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"changedSince","required":false,"description":"Sincronização: notas criadas ou alteradas a partir deste instante (ISO 8601). Ignora `page`"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false,"description":"Sincronização: o `meta.nextCursor` da página anterior. Tem precedência sobre `changedSince`"}],"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Só na sincronização: posição depois da última nota entregue. Guarde-o mesmo no fim — é o marco da próxima rodada"},"hasMore":{"type":"boolean","description":"Só na sincronização: há mais notas depois desta página"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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 e dos itens informados. Identifique o cliente por `clientId` (já cadastrado) OU por `client` (objeto inline, que cria/reusa o cliente na hora — reusa quando o `document` casa). Cada imposto do item é resolvido CAMPO A CAMPO, do mais específico ao mais genérico: o que vier no ITEM (a nota sempre prevalece) → a Regra Fiscal indicada (`taxRuleId` do item, senão do documento, senão a vinculada ao produto) → a tributação própria do PRODUTO (`productId` — ver GET /v1/products) → o template fiscal (`templateId`) → as regras padrão da empresa (GET /v1/tax-rules). A regra casa por UF, tipo de cliente e CFOP da operação. NCM e CFOP ausentes vêm do produto e, sem produto, da empresa. O `templateId` (ver GET /v1/fiscal-templates) também pré-preenche natureza da operação e código de serviço nos campos não informados. Use `emit: true` para já disparar a emissão (assíncrona) — ou chame depois `POST /fiscal-documents/{id}/emit`. **Idempotência:** mande o header `Idempotency-Key` (1–100 caracteres `[A-Za-z0-9_.:-]`, único por empresa) para repetir a chamada sem risco de nota em dobro: a mesma chave com o mesmo corpo responde **200** com a nota JÁ criada (header `Idempotent-Replayed: true`), sem criar nem emitir de novo; com outro corpo, **422** `idempotency_key_mismatch`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento"},"clientId":{"type":"string","nullable":true,"description":"ID de um cliente já cadastrado nesta empresa. Informe `clientId` OU `client` (um dos dois é obrigatório)."},"client":{"type":"object","properties":{"name":{"type":"string","description":"Nome/razão social do cliente"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (só dígitos ou formatado). Se casar um cliente já existente desta empresa, ele é reusado (idempotente). Pode ser vazio (consumidor final) — SEFAZ aceita NF-e sem identificação."},"documentType":{"type":"string","enum":["CPF","CNPJ","FOREIGN","OTHER"],"nullable":true,"description":"Tipo do documento. Inferido pelo documento quando omitido."},"type":{"type":"string","enum":["INDIVIDUAL","COMPANY","FOREIGN"],"nullable":true,"description":"Tipo do cliente. Inferido pelo documento quando omitido."},"tradingName":{"type":"string","nullable":true,"description":"Nome fantasia"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobilePhone":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual"},"municipalRegistration":{"type":"string","nullable":true,"description":"Inscrição municipal"},"zipCode":{"type":"string","nullable":true,"description":"CEP"},"street":{"type":"string","nullable":true,"description":"Logradouro"},"number":{"type":"string","nullable":true,"description":"Número"},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Bairro"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true,"description":"UF (2 letras)"},"municipalityCode":{"type":"string","nullable":true,"description":"Código IBGE do município"},"country":{"type":"string","nullable":true,"description":"País. Default: Brasil."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (BACEN). Default: 1058 (Brasil)."}},"required":["name"],"additionalProperties":false,"nullable":true,"description":"Cliente inline — cria/reusa o cliente junto da nota. Alternativa ao `clientId`. Reusa um cliente existente quando o `document` casa."},"operationNature":{"type":"string","description":"Natureza da operação (<natOp>, até 60 caracteres). Ausente = a declarada pela regra fiscal do item; sem ela, 'Venda de mercadoria' (NF-e/NFC-e) ou 'Prestação de serviços' (NFS-e)."},"buyerPresence":{"type":"string","enum":["0","1","2","3","4","5","9"],"nullable":true,"description":"<indPres> — presença do comprador. 0=não se aplica · 1=presencial · 2=internet · 3=teleatendimento · 4=entrega a domicílio (NFC-e) · 5=presencial fora do estabelecimento · 9=não presencial, outros. Omita para automático: vale o padrão da empresa e, sem ele, a origem do documento (integração=2 na NF-e e 4 na NFC-e; manual=2/1). A NFC-e só aceita 1, 4 e 5 — outro valor é recusado com 422."},"issExigibility":{"type":"string","enum":["1","2","3","4","5","6","7"],"nullable":true,"description":"Exigibilidade do ISS (NFS-e). 1=exigível · 2=não incidência · 3=isenção · 4=exportação de serviço · 5=imunidade · 6=suspensa por decisão judicial · 7=suspensa por processo administrativo. Omita para herdar a regra fiscal de NFS-e e, sem ela, exigível. As duas suspensões (6 e 7) exigem `issSuspensionProcess` — sem ele, 422."},"issSuspensionProcess":{"type":"string","nullable":true,"description":"Número do processo que concedeu a suspensão. Obrigatório com issExigibility 6 ou 7; ignorado nas demais."},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true,"description":"<mdPrestacao> — 0=desconhecido · 1=transfronteiriço · 2=consumo no Brasil · 3=presença comercial no exterior · 4=movimento temporário de pessoas físicas."},"vinculoEntrePartes":{"type":"string","nullable":true,"description":"<vincPrest> — 0=sem vínculo · 1=controlada · 2=controladora · 3=coligada · 4=matriz · 5=filial ou sucursal · 6=outro · 9=desconhecido. Não existe 7 nem 8."},"moeda":{"type":"string","nullable":true,"description":"<tpMoeda> — código de 3 dígitos da tabela do BACEN, NÃO o ISO 4217: dólar americano é 220 (não 840) e euro é 978. Os dois casam com [0-9]{3}, então o código errado sai AUTORIZADO declarando outra moeda."},"valorNaMoeda":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true,"description":"<vServMoeda> — valor do serviço NA MOEDA ESTRANGEIRA, não em reais. É o único campo do grupo sem padrão na empresa: varia a cada operação."},"mecanismoPrestador":{"type":"string","nullable":true,"description":"<mecAFComexP> — mecanismo de apoio ao comércio exterior do PRESTADOR (00 a 08)."},"mecanismoTomador":{"type":"string","nullable":true,"description":"<mecAFComexT> — mecanismo do TOMADOR (00 a 26). Tabela DIFERENTE da do prestador apesar do nome parecido: só 00 e 01 coincidem."},"movimentacaoTemporaria":{"type":"string","nullable":true,"description":"<movTempBens> — 0=desconhecido · 1=não · 2=vinculada a DI · 3=vinculada a DE."},"enviarAoMdic":{"type":"string","nullable":true,"description":"<mdic> — 0=não compartilhar · 1=compartilhar com o MDIC."},"numeroDi":{"type":"string","nullable":true,"description":"<nDI> — número da Declaração de Importação (opcional)."},"numeroRe":{"type":"string","nullable":true,"description":"<nRE> — número do Registro de Exportação (opcional)."}},"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS (NFS-e do Padrão Nacional) — comércio exterior de serviço. Override DESTA nota sobre o padrão da empresa (Configurações → NFS-e), campo a campo: o que vier vazio herda. Os OITO primeiros campos saem juntos no XML ou não sai nenhum — faltando qualquer um (na nota e na empresa), a nota é emitida SEM o grupo, porque meia sequência é recusada pelo esquema. Só vale para os municípios do Padrão Nacional."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador (grupo <infIntermed>) — o marketplace em que a venda aconteceu. Anda JUNTO com `intermediarySellerId`: um sem o outro é recusado com 422. Omita nos dois em venda direta. Quando a nota vem de uma integração, o default é o cadastrado nela."},"intermediarySellerId":{"type":"string","nullable":true,"description":"<idCadIntTran> — identificação do VENDEDOR dentro do marketplace (2 a 60 caracteres)."},"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)"},"nbsCode":{"type":"string","nullable":true,"description":"Código NBS (`<cNBS>`, 9 dígitos; pontos são normalizados). Sem valor, herda do produto e depois do padrão da empresa."},"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"},"freightValue":{"type":"number","minimum":0,"nullable":true,"description":"<vFrete> do PRÓPRIO item (R$). Soma-se ao rateio do frete da nota. Entra no total da nota e na base do ICMS/ST."},"insuranceValue":{"type":"number","minimum":0,"nullable":true,"description":"<vSeg> do item (R$). Entra no total da nota."},"otherValue":{"type":"number","minimum":0,"nullable":true,"description":"<vOutro> — outras despesas acessórias do item (R$). Entra no total da nota."},"discountValue":{"type":"number","minimum":0,"nullable":true,"description":"<vDesc> do PRÓPRIO item (R$). Soma-se ao rateio do desconto da nota e é abatido do total."},"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},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — CST 20/70. A nota prevalece: preenchido, vence o produto e a regra."},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST (4 = MVA, 6 = valor da operação). A nota prevalece: preenchida, vence o produto e a regra."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%). A nota prevalece sobre produto e regra."},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%). A nota prevalece sobre produto e regra."},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota do ICMS-ST no destino (%). A nota prevalece sobre produto e regra."},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — CSOSN 101/201. A nota prevalece sobre produto e regra."},"batches":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string","minLength":1,"description":"<nLote> — até 20 caracteres."},"quantity":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"<qLote> — 3 casas."},"producedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"<dFab> — AAAA-MM-DD, sem hora."},"expiresAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"<dVal> — AAAA-MM-DD. Informe o último dia do mês quando a validade não especifica o dia."},"aggregationCode":{"type":"string","nullable":true,"description":"<cAgreg>."}},"required":["batch","quantity","producedAt","expiresAt"],"additionalProperties":false},"maxItems":500,"nullable":true,"description":"<rastro> — os LOTES deste item. Obrigatório para alimentos, bebidas, medicamentos e defensivos: é o que permite o recall e a conferência de validade na entrada. 🔴 São vários porque a mesma linha da nota pode cobrir quantidade que saiu de mais de um lote; a soma dos `quantity` é a quantidade do item. Lote sem número, sem quantidade ou com data fora de AAAA-MM-DD é DESCARTADO — meia sequence reprovaria o schema de uma nota que, sem o grupo, sairia."},"purchaseOrder":{"type":"string","nullable":true,"description":"<xPed> — pedido de compra DESTE item (até 15 caracteres; o que passar é truncado, não recusado). Cliente B2B confere a nota contra o pedido antes de pagar."},"purchaseOrderItem":{"type":"string","nullable":true,"description":"<nItemPed> — a linha do pedido (até 6 dígitos). Valor fora do formato é DESCARTADO: um número truncado apontaria para a linha errada do pedido, que é pior que não apontar para nenhuma."},"icmsDesonValue":{"type":"number","minimum":0,"nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90. Omitido, é CALCULADO a partir da alíquota: imposto cheio nos CST sem destaque, e a diferença contra a base cheia nos CST 20 e 70."},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS). 🔴 A tabela aceita valores DIFERENTES por CST: 3/9/10/11/12 no 20; 6/7/9 no 30; 1/3/4/5/6/7/8/9/10/11/16/90 no 40, 41 e 50; 3/9/12 no 70 e no 90. Motivo fora da tabela do CST é recusado com 422."},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — quando verdadeiro, o valor desonerado ABATE o total da nota (vNF). Ausente vale como falso, que é o comportamento de toda nota emitida até aqui."},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51. Só ele é enviado: vICMSOp, vICMSDif e vICMS são calculados a partir da base e da alíquota. 100 é o caso comum (diferimento integral) e resulta em vICMS 0,00 — que é diferente de isenção."},"icmsStRetBase":{"type":"number","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$). A nota prevalece sobre o produto."},"icmsStRetRate":{"type":"number","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %). A nota prevalece sobre o produto."},"icmsSubstitutoValue":{"type":"number","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional. A nota prevalece sobre o produto."},"icmsStRetValue":{"type":"number","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$). A nota prevalece sobre o produto."},"fcpStRetBase":{"type":"number","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$). A nota prevalece sobre o produto."},"fcpStRetRate":{"type":"number","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %). A nota prevalece sobre o produto."},"fcpStRetValue":{"type":"number","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$). A nota prevalece sobre o produto."},"cest":{"type":"string","nullable":true,"description":"CEST do item (7 dígitos, pontos opcionais). Vazio = o do produto (`productId`), resolvido na emissão. Exigido quando o ICMS tem ST."},"productId":{"type":"string","nullable":true,"description":"ID de um produto desta empresa (GET /v1/products). Liga o item ao cadastro: a tributação própria do produto e o CEST dele passam a valer, e NCM/CFOP ausentes vêm do produto. Produto de outra empresa é RECUSADO com 422 `invalid_product`."},"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 e a regra do produto. Os campos de imposto explícitos acima têm prioridade sobre ela."},"rtcCClassTrib":{"type":"string","pattern":"^\\d{6}$","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos) deste item. Vazio = resolvido pela hierarquia na emissão (regra do produto → produto → template → empresa). O código é conferido contra a tabela oficial: existência, vigência e modelo. Código fora dela é ACEITO (pode ser de publicação mais nova) — a SEFAZ não rejeita código inexistente, e o erro só apareceria na apuração."},"rtcCst":{"type":"string","pattern":"^\\d{3}$","nullable":true,"description":"CST do IBS/CBS. Deixe vazio: são os 3 primeiros dígitos do `rtcCClassTrib`, e o sistema o deriva. Informar os dois com valores divergentes é RECUSADO — seria uma combinação que não existe."},"rtcAjusteIbs":{"type":"number","nullable":true,"description":"Valor de IBS do grupo de ajuste (gTransfCred no CST 800, gAjusteCompet no 811). DECLARADO, não calculado — esses CST não têm base nem alíquota. Exige `rtcAjusteCbs` junto: o grupo é tudo-ou-nada, e zero é um valor válido."},"rtcAjusteCbs":{"type":"number","nullable":true,"description":"Valor de CBS do grupo de ajuste. Ver `rtcAjusteIbs`."},"rtcEstornoIbs":{"type":"number","nullable":true,"description":"vIBSEstCred do grupo gEstornoCred, exigido pelo indicador do cClassTrib. Exige `rtcEstornoCbs` junto."},"rtcEstornoCbs":{"type":"number","nullable":true,"description":"vCBSEstCred do grupo gEstornoCred. Ver `rtcEstornoIbs`."},"rtcCompetApur":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","nullable":true,"description":"Competência do período de apuração (AAAA-MM, a partir de 2025-01). Exigida por gAjusteCompet (CST 811) e gCredPresIBSZFM (810)."},"rtcZfmTipo":{"type":"string","enum":["0","1","2","3","4"],"nullable":true,"description":"tpCredPresIBSZFM — classificação do art. 450 §1º da LC 214/25, exigida pelo CST 810."},"rtcZfmValor":{"type":"number","nullable":true,"description":"vCredPresIBSZFM — valor do crédito presumido da ZFM (CST 810)."},"rtcCredPresCodigo":{"type":"string","pattern":"^\\d{1,2}$","nullable":true,"description":"cCredPres — código do crédito presumido da OPERAÇÃO (gCredPresOper), da tabela publicada no IT RT 2025.002. Exigido quando o cClassTrib pede o grupo (ex.: 000003, 410014). Código fora da tabela é aceito com AVISO na emissão — a tabela muda por informe técnico."},"rtcCredPresBase":{"type":"number","minimum":0,"nullable":true,"description":"vBCCredPres — base de cálculo do crédito presumido. Obrigatória com o código."},"rtcCredPresIbsPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":100,"nullable":true,"description":"pCredPres do IBS (gIBSCredPres), quando o EMITENTE aproveita o crédito. Sem `rtcCredPresIbsValor`, o valor sai da conta base × percentual."},"rtcCredPresIbsValor":{"type":"number","minimum":0,"nullable":true,"description":"Valor do crédito presumido do IBS. Exige `rtcCredPresIbsPct`."},"rtcCredPresCbsPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":100,"nullable":true,"description":"pCredPres da CBS (gCBSCredPres). Ver `rtcCredPresIbsPct`."},"rtcCredPresCbsValor":{"type":"number","minimum":0,"nullable":true,"description":"Valor do crédito presumido da CBS. Exige `rtcCredPresCbsPct`."},"rtcCredPresCondSus":{"type":"boolean","nullable":true,"description":"Crédito sob condição suspensiva: os valores saem em vCredPresCondSus em vez de vCredPres."},"rtcRefChave":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos) do documento cujo ITEM este ajusta (det/DFeReferenciado). É distinto do `referencedAccessKey` do documento, que referencia a nota inteira: numa nota de crédito que corrige 3 itens de uma venda de 30, só este responde qual linha. Chave malformada é IGNORADA, nunca enviada."},"rtcRefItem":{"type":"integer","minimum":1,"maximum":990,"nullable":true,"description":"Número do item no documento referenciado (nItem). Opcional — sem ele o ajuste aponta o documento, não a linha."}},"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","FOOD_VOUCHER","MEAL_VOUCHER","GIFT_CARD","FUEL_VOUCHER","BANK_DEPOSIT","DIGITAL_WALLET","PIX_STATIC","CASHBACK","PIX_AUTOMATIC","TEF_TRANSFER","LATER_PAYMENT"],"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"},"paidAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true,"description":"<dPag> — a data em que o pagamento OCORREU (AAAA-MM-DD), que pode não ser a da emissão."},"payerCnpj":{"type":"string","nullable":true,"description":"<CNPJPag> — CNPJ do estabelecimento onde o pagamento foi processado, quando é OUTRO que não o emitente (rede de lojas com credenciamento centralizado). 🔴 Sai JUNTO com `payerState`: é uma sequence no leiaute, e só um dos dois faz os DOIS serem descartados na emissão."},"payerState":{"type":"string","minLength":2,"maxLength":2,"nullable":true,"description":"<UFPag> — a UF daquele estabelecimento. Anda com `payerCnpj`."},"receiverCnpj":{"type":"string","nullable":true,"description":"<CNPJReceb> — CNPJ de quem RECEBEU o pagamento."},"terminalId":{"type":"string","nullable":true,"description":"<idTermPag> — identificador do terminal (POS) usado."}},"required":["method","value"],"additionalProperties":false}},"duplicates":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","nullable":true,"description":"Número da parcela (<nDup>). Gerado como \"001\", \"002\"… se omitido."},"dueDate":{"type":"string","description":"Vencimento (<dVenc>) no formato AAAA-MM-DD. Data pura, sem hora."},"value":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Valor da parcela (<vDup>)."}},"required":["dueDate","value"],"additionalProperties":false},"description":"Parcelas da cobrança (grupo <cobr> da NF-e). Presença indica venda a prazo: o XML sai com indPag=1 e a DANFE ganha o bloco FATURA/DUPLICATAS. A SOMA DAS PARCELAS PRECISA FECHAR EXATAMENTE com o total do documento — diferença de um centavo é recusada com 400. Omita em venda à vista."},"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."},"templateId":{"type":"string","nullable":true,"description":"ID de um template fiscal (GET /v1/fiscal-templates) a aplicar na venda. Pré-preenche natureza da operação, CFOP/ICMS (NF-e) ou código de serviço (NFS-e) — só nos campos que você NÃO enviou (fill-empty). Valores explícitos no item/documento têm prioridade."},"transport":{"type":"object","properties":{"freightType":{"type":"string","enum":["SENDER","RECIPIENT","THIRD_PARTY","OWN_SENDER","OWN_RECIPIENT","NO_FREIGHT"],"description":"modFrete — quem paga o frete: SENDER=0 (emitente), RECIPIENT=1 (destinatário), THIRD_PARTY=2 (terceiros), OWN_SENDER=3 e OWN_RECIPIENT=4 (transporte próprio), NO_FREIGHT=9 (sem transporte, default)."},"freightValue":{"type":"number","minimum":0,"description":"Valor do frete (<vFrete>). Entra no total da nota."},"carrierId":{"type":"string","nullable":true,"description":"ID de uma transportadora desta empresa (GET /v1/carriers). Transportadora de outra empresa é RECUSADA com 422 — não descartada em silêncio."},"vehiclePlate":{"type":"string","nullable":true,"description":"Placa DESTA viagem, normalizada para o formato do XSD. Vazio usa o veículo padrão da frota da transportadora."},"vehicleState":{"type":"string","nullable":true,"description":"UF do veículo. OBRIGATÓRIA quando `vehiclePlate` é informada, na MESMA requisição: o <UF> do <veicTransp> é enumerado no XSD e placa sem UF seria rejeição 215 na emissão."},"vehicleRntc":{"type":"string","nullable":true,"description":"RNTC do veículo (ANTT)"},"volumeQuantity":{"type":"integer","minimum":0,"nullable":true,"description":"Quantidade de volumes (<qVol>)"},"volumeSpecies":{"type":"string","nullable":true,"description":"Espécie dos volumes (<esp>): CAIXA, PALETE, SACO..."},"volumeBrand":{"type":"string","nullable":true,"description":"Marca dos volumes (<marca>)"},"volumeNumbering":{"type":"string","nullable":true,"description":"Numeração dos volumes (<nVol>)"},"volumeGrossWeight":{"type":"number","minimum":0,"nullable":true,"description":"Peso bruto em kg (<pesoB>)"},"volumeNetWeight":{"type":"number","minimum":0,"nullable":true,"description":"Peso líquido em kg (<pesoL>)"}},"additionalProperties":false,"nullable":true,"description":"Grupo X (<transp>) da NF-e — transportadora, veículo e volumes. É o que preenche o quadro TRANSPORTADOR / VOLUMES TRANSPORTADOS da DANFE. Omita em venda sem transporte (serviço, digital, retirada em mãos): a nota sai exatamente como sempre saiu. NFS-e não tem esse grupo."},"discountValue":{"type":"number","minimum":0,"nullable":true,"description":"Desconto INCONDICIONAL da nota. É rateado entre os itens (`det/prod/vDesc`) e ABATE a base do imposto — não é só um abatimento do total. Desconto condicional (por antecipação de pagamento) não entra aqui: ele não reduz a base."},"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."},"rtcCreditType":{"type":"string","enum":["01","02","03","04","05"],"nullable":true,"description":"Nota de CRÉDITO da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo codificado: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização do destinatário; 04=redução de valores; 05=transferência de crédito na sucessão. Só NF-e (modelo 55); a nota sai sem cobrança (tPag=90). Mutuamente exclusivo com rtcDebitType."},"rtcDebitType":{"type":"string","enum":["01","02","03","04","05","06","07","08"],"nullable":true,"description":"Nota de DÉBITO da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo codificado: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples Nacional. Só NF-e (modelo 55); a nota sai sem cobrança (tPag=90). Mutuamente exclusivo com rtcCreditType."},"isDevolution":{"type":"boolean","nullable":true,"description":"Nota de DEVOLUÇÃO (finNFe=4). O tipo da operação (entrada ou saída) NÃO vem daqui: sai da faixa do CFOP dos itens — 1xxx/2xxx é entrada (cliente devolvendo a você), 5xxx/6xxx é saída (você devolvendo ao fornecedor). Mutuamente exclusiva com as notas de crédito/débito da RTC. Informe também `referencedAccessKey`: com ela, o IPI devolvido de cada item é lido do XML da nota original e sai no grupo <impostoDevol>; sem ela, ou se a chave não achar a nota, a devolução é criada sem esse grupo (ele é opcional no leiaute)."},"referencedAccessKey":{"type":"string","pattern":"^\\d{44}$","nullable":true,"description":"Chave de acesso (44 dígitos) da NF-e original ajustada ou devolvida — vira <refNFe> na emissão. Recomendado nas notas de crédito/débito, e é o que destrava o <impostoDevol> na devolução."},"fiscalPurpose":{"type":"string","enum":["COMPLEMENTAR","AJUSTE"],"nullable":true,"description":"Finalidade da nota (B1). COMPLEMENTAR = finNFe 2, para corrigir valor ou imposto declarado A MENOS numa nota já autorizada (a complementar carrega só a DIFERENÇA). AJUSTE = finNFe 3. 🔴 Mutuamente exclusiva com `isDevolution` e com as notas de crédito/débito — a nota tem UMA finalidade. As duas EXIGEM o documento referenciado (`referencedAccessKey` ou `references`)."},"places":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["PICKUP","DELIVERY"],"description":"PICKUP = <retirada> (de onde a mercadoria SAI) · DELIVERY = <entrega> (para onde ela VAI). Um de cada, no máximo."},"cnpj":{"type":"string","nullable":true,"description":"CNPJ de quem retira/recebe — OU o CPF."},"cpf":{"type":"string","nullable":true,"description":"CPF de quem retira/recebe — OU o CNPJ."},"name":{"type":"string","nullable":true,"description":"Nome/razão social do local."},"street":{"type":"string","minLength":1,"description":"Logradouro (xLgr)."},"number":{"type":"string","minLength":1,"description":"Número (nro)."},"complement":{"type":"string","nullable":true,"description":"Complemento (xCpl)."},"neighborhood":{"type":"string","minLength":1,"description":"Bairro (xBairro)."},"cityCode":{"type":"string","minLength":1,"description":"Código IBGE do município (cMun)."},"cityName":{"type":"string","minLength":1,"description":"Nome do município (xMun)."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"UF."},"zipCode":{"type":"string","nullable":true,"description":"CEP."},"countryCode":{"type":"string","nullable":true,"description":"Código do país (cPais)."},"countryName":{"type":"string","nullable":true,"description":"Nome do país (xPais)."},"phone":{"type":"string","nullable":true,"description":"Telefone."},"email":{"type":"string","nullable":true,"description":"E-mail."},"stateRegistration":{"type":"string","nullable":true,"description":"Inscrição estadual de quem retira/recebe."}},"required":["kind","street","number","neighborhood","cityCode","cityName","state"],"additionalProperties":false},"maxItems":2,"nullable":true,"description":"Local de RETIRADA e de ENTREGA (<retirada>/<entrega>), quando diferentes do remetente e do destinatário — e-commerce com entrega em outro endereço, dropshipping, venda à ordem. Um de cada `kind`; o segundo com o mesmo kind é descartado."},"competence":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","nullable":true,"description":"NFS-e: competência do serviço (<dCompet>), em AAAA-MM ou AAAA-MM-DD. Ausente = a data de emissão, que é o comportamento de toda nota. Serve a quem fatura no mês seguinte ao serviço — mensalidade, contador, manutenção."},"serviceMunicipalityCode":{"type":"string","nullable":true,"description":"NFS-e: código IBGE do município onde o serviço foi PRESTADO, quando diferente do que a Regra Fiscal resolveria. 🔴 Serviço em obra, em evento ou na sede do cliente ficava declarado no município da empresa, e o ISS vai para a prefeitura errada — o que não volta como rejeição, volta na fiscalização."},"serviceDeductionValue":{"type":"number","minimum":0,"nullable":true,"description":"NFS-e: dedução/redução da base em VALOR (<vDR> do <vDedRed>). 🔴 VENCE o percentual da Regra Fiscal: agência de viagem, turismo e construção civil deduzem o repasse ao fornecedor e o material aplicado, que mudam a cada nota e não cabem numa alíquota de cadastro. O grupo é um `xs:choice` — percentual e valor nunca saem juntos."},"construction":{"type":"object","properties":{"registration":{"type":"string","nullable":true,"description":"Inscrição imobiliária fiscal (IPTU). NÃO identifica a obra."},"code":{"type":"string","nullable":true,"description":"Código CNO/CEI da obra (`<cObra>`)."},"cib":{"type":"string","nullable":true,"description":"Código CIB (`<cCIB>`). Só no Padrão Nacional."},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true,"description":"Endereço da obra. Só no Padrão Nacional; vai inteiro."},"techDoc":{"type":"string","nullable":true,"description":"Documento técnico: ART, RRT ou DRT. Vai no `<idDocTec>` do `<infoCompl>` no Padrão Nacional e no `<Art>` do `<ConstrucaoCivil>` no ABRASF."}},"additionalProperties":false,"nullable":true,"description":"NFS-e de construção civil (LC 7.02 e 7.05). 🔴 A identificação da obra é um `xs:choice`: informe UM e só um entre `code` (CNO/CEI), `cib` e o endereço. A inscrição imobiliária é opcional e fica FORA da escolha — ela não identifica a obra sozinha."},"substitutedDocumentId":{"type":"string","nullable":true,"description":"NFS-e: id da nota que esta SUBSTITUI. 🔴 A substituição é UMA operação, não 'cancela e emite': o grupo <subst> vai na DPS desta nota e quem cancela a antiga é a Sefin (ou, no ABRASF, o próprio SubstituirNfse). A nota indicada precisa ser uma NFS-e AUTORIZADA desta empresa, com chave de acesso."},"substitutionReason":{"type":"string","nullable":true,"description":"Código de justificativa da substituição (TSCodJustSubst): 01 desenquadramento do Simples, 02 enquadramento, 03 inclusão retroativa de imunidade, 04 exclusão retroativa, 05 rejeição pelo tomador, 99 outros. Vazio = 99. 🔴 NÃO é a tabela do cancelamento comum (1/2/9), que tem o mesmo nome de campo."},"substitutionNote":{"type":"string","nullable":true,"description":"Texto do motivo da substituição (<xMotivo>, opcional). Mínimo de 15 caracteres no schema — texto curto é completado com o rótulo do código em vez de reprovar."},"serviceFinalUse":{"type":"boolean","nullable":true,"description":"NFS-e: <indFinal> da DPS — operação de uso ou consumo PESSOAL de sócio ou administrador (art. 57 da LC 214/2025). 🔴 NÃO é o consumidor final da NF-e e não se deriva do cliente: aquele diz que o comprador é o fim da cadeia, este diz para que o serviço foi. Ausente = não."},"purchaseNote":{"type":"string","nullable":true,"description":"<xNEmp> — nota de EMPENHO. É o que o órgão público exige na nota para liquidar o pagamento."},"purchaseOrderRef":{"type":"string","nullable":true,"description":"<xPed> do grupo <compra> — o pedido de compra da NOTA INTEIRA. 🔴 Não confundir com o `purchaseOrder` do ITEM: os dois existem no leiaute e não são o mesmo campo."},"purchaseContract":{"type":"string","nullable":true,"description":"<xCont> — número do contrato de compra."},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["NFE","NF_PAPEL","NF_PRODUTOR","CTE","ECF"],"description":"NFE = NF-e por chave · NF_PAPEL = nota em papel modelo 1/1A · NF_PRODUTOR = nota fiscal de produtor rural · CTE = conhecimento de transporte por chave · ECF = cupom fiscal"},"accessKey":{"type":"string","nullable":true,"description":"NFE e CTE: chave de acesso, 44 dígitos."},"stateCode":{"type":"string","nullable":true,"description":"NF_PAPEL e NF_PRODUTOR: código IBGE da UF do emitente (cUF)."},"yearMonth":{"type":"string","nullable":true,"description":"NF_PAPEL e NF_PRODUTOR: ano e mês da emissão (AAMM)."},"cnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente referenciado."},"cpf":{"type":"string","nullable":true,"description":"NF_PRODUTOR: CPF do produtor — OU o CNPJ, nunca os dois."},"stateRegistration":{"type":"string","nullable":true,"description":"NF_PRODUTOR: inscrição estadual do produtor (obrigatória)."},"model":{"type":"string","nullable":true,"description":"NF_PAPEL: 01 ou 02 · NF_PRODUTOR: 01 ou 04 · ECF: 2B, 2C ou 2D."},"series":{"type":"string","nullable":true,"description":"Série do documento (0 a 889)."},"number":{"type":"string","nullable":true,"description":"Número do documento."},"ecfNumber":{"type":"string","nullable":true,"description":"ECF: número de ordem do equipamento (nECF)."},"cooNumber":{"type":"string","nullable":true,"description":"ECF: contador de ordem de operação (nCOO)."}},"required":["kind"],"additionalProperties":false},"maxItems":999,"nullable":true,"description":"Documentos referenciados (<NFref>). Até 999, e UM tipo por item — o leiaute declara um `xs:choice`, então referenciar uma NF-e e um cupom são DOIS itens. Além da NF-e por chave, cobre a nota em PAPEL (modelo 1/1A), a nota de PRODUTOR RURAL, o CT-e e o CUPOM FISCAL. O `referencedAccessKey` continua valendo e é somado a esta lista, sem duplicar."}},"required":["type","items"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"Chave de idempotência da criação (1–100 caracteres `[A-Za-z0-9_.:-]`). Repetir a chave com o mesmo corpo devolve a nota da primeira chamada."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Repetição de uma criação com a mesma `Idempotency-Key` e o mesmo corpo: a nota que já existe","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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev (presente quando emit=true)"},"precheckErrors":{"type":"array","items":{"type":"string"},"description":"Presente quando `emit=true` mas a pré-validação de configuração reprovou: o rascunho FOI criado (por isso 201) e a emissão NÃO foi disparada. Corrija o que está listado aqui e chame POST /fiscal-documents/{id}/emit."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","runId"],"additionalProperties":false,"description":"Repetição de uma criação com a mesma `Idempotency-Key` e o mesmo corpo: a nota que já existe"}}}},"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"runId":{"type":"string","nullable":true,"description":"ID do run no Trigger.dev (presente quando emit=true)"},"precheckErrors":{"type":"array","items":{"type":"string"},"description":"Presente quando `emit=true` mas a pré-validação de configuração reprovou: o rascunho FOI criado (por isso 201) e a emissão NÃO foi disparada. Corrija o que está listado aqui e chame POST /fiscal-documents/{id}/emit."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","runId"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"taxTotals":{"type":"object","properties":{"icmsTotal":{"type":"string"},"icmsStTotal":{"type":"string","description":"ICMS-ST contido no totalValue (calculado na emissão)"},"ipiTotal":{"type":"string","description":"IPI contido no totalValue (calculado na emissão)"},"pisTotal":{"type":"string"},"cofinsTotal":{"type":"string"},"issTotal":{"type":"string"},"discountValue":{"type":"string","description":"Desconto abatido do total"},"rtcIbsTotal":{"type":"string","nullable":true,"description":"IBS destacado na nota; null quando a nota não destacou (nunca \"0.00\")"},"rtcCbsTotal":{"type":"string","nullable":true,"description":"CBS destacada na nota; null quando a nota não destacou (nunca \"0.00\")"}},"required":["icmsTotal","icmsStTotal","ipiTotal","pisTotal","cofinsTotal","issTotal","discountValue","rtcIbsTotal","rtcCbsTotal"],"additionalProperties":false,"description":"Impostos e desconto que compõem o totalValue"},"buyerPresence":{"type":"string","nullable":true,"description":"<indPres> escolhido na nota. null = automático (padrão da empresa, ou derivação pela origem do documento)."},"intermediaryDocument":{"type":"string","nullable":true,"description":"CNPJ do intermediador; null = venda direta (<indIntermed>=0)."},"intermediarySellerId":{"type":"string","nullable":true},"comExt":{"type":"object","properties":{"modoPrestacao":{"type":"string","nullable":true},"vinculoEntrePartes":{"type":"string","nullable":true},"moeda":{"type":"string","nullable":true},"valorNaMoeda":{"type":"string","nullable":true},"mecanismoPrestador":{"type":"string","nullable":true},"mecanismoTomador":{"type":"string","nullable":true},"movimentacaoTemporaria":{"type":"string","nullable":true},"enviarAoMdic":{"type":"string","nullable":true},"numeroDi":{"type":"string","nullable":true},"numeroRe":{"type":"string","nullable":true}},"required":["modoPrestacao","vinculoEntrePartes","moeda","valorNaMoeda","mecanismoPrestador","mecanismoTomador","movimentacaoTemporaria","enviarAoMdic","numeroDi","numeroRe"],"additionalProperties":false,"nullable":true,"description":"Grupo <comExt> da DPS gravado NESTA nota (comércio exterior de serviço). null = a nota não sobrescreve nada e o que vale é o padrão da empresa — não é o mesmo que 'sem comércio exterior'."},"issExigibility":{"type":"string","nullable":true,"description":"<ExigibilidadeISS> da NFS-e (ABRASF 1..7). null = exigível."},"issSuspensionProcess":{"type":"string","nullable":true},"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},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION — homologação não tem valor fiscal"},"isDevolution":{"type":"boolean","description":"Nota de devolução (finNFe=4). O tipo da operação sai da faixa do CFOP dos itens, não deste campo."},"referencedAccessKey":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e original referenciada (<refNFe>) — na devolução e nas notas de crédito/débito. null = nota sem referência."},"rtcCreditType":{"type":"string","nullable":true,"description":"Nota de crédito da Reforma Tributária (ajuste de IBS/CBS, finNFe=5). Motivo: 01=multa e juros; 02=crédito presumido IBS ZFM; 03=retorno por recusa/não localização; 04=redução de valores; 05=transferência de crédito na sucessão. null = nota comum."},"rtcDebitType":{"type":"string","nullable":true,"description":"Nota de débito da Reforma Tributária (ajuste de IBS/CBS, finNFe=6). Motivo: 01=transf. créditos p/ cooperativas; 02=anulação de crédito por saídas imunes/isentas; 03=débitos não processados na apuração; 04=multa e juros; 05=transf. de crédito na sucessão; 06=pagamento antecipado; 07=perda em estoque; 08=desenquadramento do Simples. null = nota comum."},"client":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"ID do cliente (GET /v1/clients/{id}); null se removido"},"name":{"type":"string","nullable":true,"description":"Nome/razão social (snapshot da nota)"},"document":{"type":"string","nullable":true,"description":"CPF/CNPJ (snapshot da nota)"},"documentType":{"type":"string","nullable":true,"description":"CPF | CNPJ | FOREIGN | OTHER"}},"required":["id","name","document","documentType"],"additionalProperties":false,"description":"Cliente/destinatário da nota"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação (`externalId`). É o mesmo que o webhook da nota leva, e o filtro `externalId` da lista casa com ele."},"fiscalPurpose":{"type":"string","nullable":true,"description":"<finNFe> 2/3 (COMPLEMENTAR/AJUSTE); null = normal"},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"accessKey":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"yearMonth":{"type":"string","nullable":true},"cnpj":{"type":"string","nullable":true},"cpf":{"type":"string","nullable":true},"stateRegistration":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"series":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"ecfNumber":{"type":"string","nullable":true},"cooNumber":{"type":"string","nullable":true}},"required":["kind","accessKey","stateCode","yearMonth","cnpj","cpf","stateRegistration","model","series","number","ecfNumber","cooNumber"],"additionalProperties":false},"description":"<NFref> — documentos referenciados"},"places":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"<retirada>/<entrega> — `kind` PICKUP | DELIVERY"},"purchase":{"type":"object","properties":{"note":{"type":"string","nullable":true,"description":"<xNEmp>"},"orderRef":{"type":"string","nullable":true,"description":"<xPed>"},"contract":{"type":"string","nullable":true,"description":"<xCont>"}},"required":["note","orderRef","contract"],"additionalProperties":false,"nullable":true},"competence":{"type":"string","nullable":true,"description":"NFS-e: AAAA-MM-DD; null = data de emissão"},"serviceMunicipalityCode":{"type":"string","nullable":true},"serviceFinalUse":{"type":"boolean","nullable":true},"serviceDeductionValue":{"type":"string","nullable":true},"construction":{"type":"object","properties":{"registration":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"cib":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"complement":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"techDoc":{"type":"string","nullable":true}},"required":["registration","code","cib","zipCode","street","number","complement","neighborhood","techDoc"],"additionalProperties":false,"nullable":true},"substitution":{"type":"object","properties":{"substitutedDocumentId":{"type":"string"},"reason":{"type":"string","nullable":true},"note":{"type":"string","nullable":true}},"required":["substitutedDocumentId","reason","note"],"additionalProperties":false,"nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer"},"productId":{"type":"string","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true},"cfop":{"type":"string"},"unit":{"type":"string"},"quantity":{"type":"string"},"unitValue":{"type":"string"},"totalValue":{"type":"string"},"discountValue":{"type":"string","nullable":true},"freightValue":{"type":"string","nullable":true},"insuranceValue":{"type":"string","nullable":true},"otherValue":{"type":"string","nullable":true},"nbsCode":{"type":"string","nullable":true,"description":"<cNBS> do item (NFS-e)"},"purchaseOrder":{"type":"string","nullable":true,"description":"<xPed> do item"},"purchaseOrderItem":{"type":"string","nullable":true,"description":"<nItemPed> do item"},"icms":{"type":"object","properties":{"origin":{"type":"string","nullable":true},"situation":{"type":"string","nullable":true,"description":"CST ou CSOSN"},"rate":{"type":"string","nullable":true},"desonerationValue":{"type":"string","nullable":true},"desonerationReason":{"type":"string","nullable":true},"desonerationDeduct":{"type":"boolean","nullable":true},"deferralRate":{"type":"string","nullable":true},"stRetainedBase":{"type":"string","nullable":true},"stRetainedRate":{"type":"string","nullable":true},"substituteValue":{"type":"string","nullable":true},"stRetainedValue":{"type":"string","nullable":true},"fcpStRetainedBase":{"type":"string","nullable":true},"fcpStRetainedRate":{"type":"string","nullable":true},"fcpStRetainedValue":{"type":"string","nullable":true}},"required":["origin","situation","rate","desonerationValue","desonerationReason","desonerationDeduct","deferralRate","stRetainedBase","stRetainedRate","substituteValue","stRetainedValue","fcpStRetainedBase","fcpStRetainedRate","fcpStRetainedValue"],"additionalProperties":false},"ibsCbs":{"type":"object","properties":{"cst":{"type":"string","nullable":true},"cClassTrib":{"type":"string","nullable":true},"amounts":{"type":"object","properties":{"taxBase":{"type":"string","nullable":true,"description":"vBC do gIBSCBS"},"ibsStateRate":{"type":"string","nullable":true,"description":"pIBSUF (%)"},"ibsStateValue":{"type":"string","nullable":true,"description":"vIBSUF"},"ibsMunicipalRate":{"type":"string","nullable":true,"description":"pIBSMun (%)"},"ibsMunicipalValue":{"type":"string","nullable":true,"description":"vIBSMun"},"cbsRate":{"type":"string","nullable":true,"description":"pCBS (%)"},"cbsValue":{"type":"string","nullable":true,"description":"vCBS"}},"required":["taxBase","ibsStateRate","ibsStateValue","ibsMunicipalRate","ibsMunicipalValue","cbsRate","cbsValue"],"additionalProperties":false,"nullable":true,"description":"Destaque de IBS/CBS CALCULADO na emissão para esta linha — a soma das linhas fecha com `taxTotals.rtcIbsTotal`/`rtcCbsTotal`. `null` quando a linha não destacou (rascunho, nota sem o grupo, nota de ajuste); nunca um objeto de zeros, que afirmaria destaque zerado."},"adjustment":{"type":"object","properties":{"ibs":{"type":"string","nullable":true},"cbs":{"type":"string","nullable":true}},"required":["ibs","cbs"],"additionalProperties":false,"nullable":true,"description":"Grupo de ajuste DECLARADO (gTransfCred/gAjusteCompet) — o `rtcAjusteIbs`/`rtcAjusteCbs` do POST. `null` quando não há."},"creditReversal":{"type":"object","properties":{"ibs":{"type":"string","nullable":true},"cbs":{"type":"string","nullable":true}},"required":["ibs","cbs"],"additionalProperties":false,"nullable":true,"description":"gEstornoCred — o `rtcEstornoIbs`/`rtcEstornoCbs` do POST."},"assessmentPeriod":{"type":"string","nullable":true,"description":"Competência de apuração (AAAA-MM) — o `rtcCompetApur` do POST."},"zfmPresumedCredit":{"type":"object","properties":{"type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["type","value"],"additionalProperties":false,"nullable":true,"description":"gCredPresIBSZFM — `rtcZfmTipo`/`rtcZfmValor` do POST."},"referencedItem":{"type":"object","properties":{"accessKey":{"type":"string","nullable":true},"item":{"type":"integer","nullable":true}},"required":["accessKey","item"],"additionalProperties":false,"nullable":true,"description":"det/DFeReferenciado — `rtcRefChave`/`rtcRefItem` do POST."},"operationPresumedCredit":{"type":"object","properties":{"code":{"type":"string","nullable":true},"taxBase":{"type":"string","nullable":true},"ibs":{"type":"object","properties":{"rate":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["rate","value"],"additionalProperties":false,"nullable":true},"cbs":{"type":"object","properties":{"rate":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"required":["rate","value"],"additionalProperties":false,"nullable":true},"suspensiveCondition":{"type":"boolean"}},"required":["code","taxBase","ibs","cbs","suspensiveCondition"],"additionalProperties":false,"nullable":true,"description":"gCredPresOper — os `rtcCredPres*` do POST. `null` quando não há."}},"required":["cst","cClassTrib","amounts","adjustment","creditReversal","assessmentPeriod","zfmPresumedCredit","referencedItem","operationPresumedCredit"],"additionalProperties":false},"batches":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string"},"quantity":{"type":"string"},"producedAt":{"type":"string","description":"AAAA-MM-DD"},"expiresAt":{"type":"string","description":"AAAA-MM-DD"},"aggregationCode":{"type":"string","nullable":true}},"required":["batch","quantity","producedAt","expiresAt","aggregationCode"],"additionalProperties":false},"description":"<rastro> — lotes do item"}},"required":["sequence","productId","code","description","ncm","cest","cfop","unit","quantity","unitValue","totalValue","discountValue","freightValue","insuranceValue","otherValue","nbsCode","purchaseOrder","purchaseOrderItem","icms","ibsCbs","batches"],"additionalProperties":false}},"payments":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer"},"method":{"type":"string"},"value":{"type":"string"},"description":{"type":"string","nullable":true},"cardFlag":{"type":"string","nullable":true},"cardCNPJ":{"type":"string","nullable":true},"cardAuthorization":{"type":"string","nullable":true},"pixKey":{"type":"string","nullable":true},"pixTxId":{"type":"string","nullable":true},"paidAt":{"type":"string","nullable":true,"description":"<dPag> — AAAA-MM-DD"},"payerCnpj":{"type":"string","nullable":true},"payerState":{"type":"string","nullable":true},"receiverCnpj":{"type":"string","nullable":true},"terminalId":{"type":"string","nullable":true}},"required":["sequence","method","value","description","cardFlag","cardCNPJ","cardAuthorization","pixKey","pixTxId","paidAt","payerCnpj","payerState","receiverCnpj","terminalId"],"additionalProperties":false}},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"CANCELLATION | CORRECTION | CONFIRMATION | DELIVERY_RECEIPT | DELIVERY_RECEIPT_CANCELLATION | …"},"code":{"type":"string","description":"tpEvento (ex.: 110111, 110130)"},"sequence":{"type":"integer"},"protocol":{"type":"string","nullable":true},"authorized":{"type":"boolean"},"rejectionReason":{"type":"string","nullable":true},"createdAt":{"type":"string"},"delivery":{"type":"object","properties":{"deliveredAt":{"type":"string","nullable":true},"receiverName":{"type":"string","nullable":true},"receiverDocument":{"type":"string","nullable":true},"latitude":{"type":"string","nullable":true},"longitude":{"type":"string","nullable":true},"proofHash":{"type":"string","nullable":true}},"required":["deliveredAt","receiverName","receiverDocument","latitude","longitude","proofHash"],"additionalProperties":false,"nullable":true,"description":"Só no DELIVERY_RECEIPT (110130)"},"referencedProtocol":{"type":"string","nullable":true,"description":"No cancelamento do comprovante (110131): o protocolo que ele cancela"}},"required":["type","code","sequence","protocol","authorized","rejectionReason","createdAt","delivery","referencedProtocol"],"additionalProperties":false}},"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},"duplicates":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"<nDup>"},"dueDate":{"type":"string","description":"<dVenc> — AAAA-MM-DD"},"value":{"type":"string","description":"<vDup> — decimal como string"}},"required":["number","dueDate","value"],"additionalProperties":false},"description":"Parcelas da cobrança. Lista vazia = venda à vista (sem grupo <cobr>)."},"transport":{"type":"object","properties":{"freightType":{"type":"string","nullable":true,"description":"SENDER | RECIPIENT | THIRD_PARTY | OWN_* | NO_FREIGHT"},"freightValue":{"type":"string","description":"Decimal como string"},"carrierId":{"type":"string","nullable":true},"carrierName":{"type":"string","nullable":true,"description":"Snapshot: sobrevive à exclusão da transportadora"},"carrierDocument":{"type":"string","nullable":true,"description":"Snapshot"},"vehiclePlate":{"type":"string","nullable":true},"vehicleState":{"type":"string","nullable":true},"vehicleRntc":{"type":"string","nullable":true},"volumeQuantity":{"type":"integer","nullable":true},"volumeSpecies":{"type":"string","nullable":true},"volumeBrand":{"type":"string","nullable":true},"volumeNumbering":{"type":"string","nullable":true},"volumeGrossWeight":{"type":"string","nullable":true,"description":"kg, decimal como string"},"volumeNetWeight":{"type":"string","nullable":true,"description":"kg, decimal como string"}},"required":["freightType","freightValue","carrierId","carrierName","carrierDocument","vehiclePlate","vehicleState","vehicleRntc","volumeQuantity","volumeSpecies","volumeBrand","volumeNumbering","volumeGrossWeight","volumeNetWeight"],"additionalProperties":false,"nullable":true,"description":"Grupo X (<transp>). null quando a nota não tem transporte."}},"required":["id","type","status","series","number","accessKey","totalValue","taxTotals","buyerPresence","intermediaryDocument","intermediarySellerId","comExt","issExigibility","issSuspensionProcess","issueDateTime","authorizationDate","pdfUrl","xmlUrl","environment","isDevolution","referencedAccessKey","rtcCreditType","rtcDebitType","client","externalId","fiscalPurpose","references","places","purchase","competence","serviceMunicipalityCode","serviceFinalUse","serviceDeductionValue","construction","substitution","items","payments","events","nfseNumber","verificationCode","protocolNumber","rejectionReason","cancellationReason","cancellationDate","duplicates","transport"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"cancellationReason":{"type":"string","enum":["1","2","9"],"nullable":true,"description":"NFS-e (Padrão Nacional): <cMotivo> do evento e101101 — 1 = erro na emissão, 2 = serviço NÃO PRESTADO, 9 = outros. Ausente vale 1. 🔴 São coisas diferentes e a prefeitura lê a diferença: erro de emissão diz que a operação existiu e o documento saiu errado; serviço não prestado diz que a operação não aconteceu. Ignorado na NF-e, cujo evento de cancelamento não tem código de motivo."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/delivery-receipt":{"post":{"summary":"Registra o comprovante de entrega da NF-e","tags":["Fiscal Documents"],"description":"Registra na SEFAZ (Ambiente Nacional) o evento 110130 — quem recebeu a mercadoria, quando e o hash da imagem do comprovante (canhoto assinado, assinatura, documento). Só NF-e modelo 55 AUTORIZADA. Síncrono. 🔴 Com o comprovante registrado a NF-e NÃO pode ser cancelada (rejeição 826) e não aceita outro comprovante (825): cancele-o antes com `DELETE`. A imagem é guardada pela plataforma; a SEFAZ recebe só o hash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deliveredAt":{"type":"string","format":"date-time","description":"Data e hora da entrega, ISO 8601 com fuso. Não pode ser futura nem anterior à emissão."},"receiverName":{"type":"string","minLength":2,"maxLength":60,"description":"Nome de quem recebeu"},"receiverDocument":{"type":"string","minLength":2,"maxLength":20,"description":"Documento de quem recebeu (RG, CPF ou outro)"},"latitude":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"longitude":{"type":"number","minimum":-180,"maximum":180,"nullable":true},"proof":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","application/pdf"]},"base64":{"type":"string","minLength":1,"description":"Arquivo do comprovante em base64 (até 3 MB decodificado)"}},"required":["contentType","base64"],"additionalProperties":false}},"required":["deliveredAt","receiverName","receiverDocument","proof"],"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]},"protocol":{"type":"string","description":"Protocolo do evento no Ambiente Nacional"},"sequence":{"type":"integer"}},"required":["success","protocol","sequence"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Cancela o comprovante de entrega ativo da NF-e","tags":["Fiscal Documents"],"description":"Envia o evento 110131, que referencia o protocolo do comprovante ativo. Depois dele a NF-e volta a poder ser cancelada e aceita um novo comprovante.","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]},"protocol":{"type":"string"},"sequence":{"type":"integer"}},"required":["success","protocol","sequence"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/webhook":{"post":{"summary":"Dispara o webhook de uma nota","tags":["Fiscal Documents"],"description":"Cria uma entrega de webhook para esta nota em todos os endpoints ativos inscritos no evento. Diferente do reenvio por entrega, funciona mesmo que a nota NUNCA tenha gerado entrega — o caso de quem cadastrou o endpoint depois de já ter emitido.\n\nO evento enviado é o do estado ATUAL da nota: uma nota cancelada dispara `document.cancelled`, não `document.authorized`.\n\n**Cada chamada gera um `id` de evento NOVO** (`evt_...`), então o seu endpoint NÃO consegue deduplicá-la contra a entrega original. Chame de forma deliberada, não em laço sobre a base inteira.\n\nLimite dedicado de 60 chamadas por minuto por empresa, além do limite global da API — é o endpoint do SEU servidor que recebe a rajada.","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":{"dispatched":{"type":"number","description":"Quantidade de entregas criadas (uma por endpoint)"}},"required":["dispatched"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/titles":{"get":{"summary":"Lista as parcelas de contas a receber ou a pagar","tags":["Financeiro"],"description":"A unidade é a PARCELA, não o título: é ela que vence e é ela que recebe baixa. Por padrão lista só o que está em aberto.","parameters":[{"schema":{"type":"string","enum":["RECEIVABLE","PAYABLE"]},"in":"query","name":"kind","required":true},{"schema":{"type":"string","enum":["VENCIDAS","VENCE_HOJE","PROXIMOS_7","EM_ABERTO","TODAS","A_CONFIRMAR","D1A30","D31A60","D61A90","D91MAIS"]},"in":"query","name":"due","required":false,"description":"Recorte. `A_CONFIRMAR` é a fila de parcelas sem vencimento informado; `D1A30`…`D91MAIS` são as faixas de atraso."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Busca por descrição ou contraparte"},{"schema":{"type":"string"},"in":"query","name":"categoryId","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includeSettled","required":false,"description":"Inclui as já quitadas. Default: false."},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"pageSize","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID da parcela — use em POST .../settlements"},"titleId":{"type":"string"},"sequence":{"type":"integer","description":"Nº da parcela dentro do título"},"totalInstallments":{"type":"integer"},"description":{"type":"string"},"counterpartyName":{"type":"string","nullable":true,"description":"Cliente (receber) ou fornecedor (pagar)"},"counterpartyDocument":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"categoryId":{"type":"string","nullable":true},"categoryName":{"type":"string","nullable":true},"origin":{"type":"string","description":"MANUAL | FISCAL_DOCUMENT | RECEIVED_DOCUMENT | RECURRING | INTEGRATION"},"dueDate":{"type":"string","description":"Vencimento (YYYY-MM-DD)"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"paidAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"balance":{"type":"string","description":"amount − paidAmount: o que ainda falta"},"status":{"type":"string","description":"O que está no banco: OPEN | PARTIALLY_PAID | PAID | CANCELED"},"derivedStatus":{"type":"string","description":"Situação de exibição — inclui \"VENCIDA\", que é DERIVADA da data e nunca uma coluna. Use este campo, não `status`, para saber se atrasou."},"daysOverdue":{"type":"integer"},"dueDatePending":{"type":"boolean","description":"A nota não informou o vencimento: `dueDate` é a data de EMISSÃO, só âncora. Enquanto for true a parcela NÃO vence e fica fora do aging."},"fiscalDocumentId":{"type":"string","nullable":true}},"required":["id","titleId","sequence","totalInstallments","description","counterpartyName","counterpartyDocument","clientId","categoryId","categoryName","origin","dueDate","amount","paidAmount","balance","status","derivedStatus","daysOverdue","dueDatePending","fiscalDocumentId"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Lança uma conta a receber ou a pagar","tags":["Financeiro"],"description":"Conta à vista é 1 parcela, nunca zero. Com `schedule` os vencimentos são os que você enviar e o total vira a soma da grade.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["RECEIVABLE","PAYABLE"],"description":"RECEIVABLE (a receber) ou PAYABLE (a pagar)"},"description":{"type":"string","minLength":1},"totalAmount":{"type":"string","description":"Valor total como string decimal (\"1234.56\")"},"dueDate":{"type":"string","description":"Vencimento da 1ª parcela (YYYY-MM-DD). Ignorado quando há `schedule`."},"issueDate":{"type":"string","description":"Data de emissão (YYYY-MM-DD). Default: hoje."},"counterpartyName":{"type":"string","nullable":true},"counterpartyDocument":{"type":"string","nullable":true,"description":"CPF/CNPJ da contraparte"},"clientId":{"type":"string","nullable":true,"description":"Vínculo opcional com o cadastro de Clientes"},"categoryId":{"type":"string","nullable":true},"installments":{"type":"integer","minimum":1,"maximum":360,"description":"Nº de parcelas. Default: 1."},"interval":{"type":"string","enum":["MONTHLY","WEEKLY"]},"schedule":{"type":"array","items":{"type":"object","properties":{"dueDate":{"type":"string"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["dueDate","amount"],"additionalProperties":false},"minItems":1,"description":"Grade EXPLÍCITA de parcelas. Vence `installments`/`interval`/`totalAmount` — o total do título passa a ser a SOMA da grade. Use quando você já sabe os vencimentos em vez de derivá-los."}},"required":["kind","description","totalAmount","dueDate"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"origin":{"type":"string"},"description":{"type":"string"},"counterpartyName":{"type":"string","nullable":true},"counterpartyDocument":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"categoryId":{"type":"string","nullable":true},"categoryName":{"type":"string","nullable":true},"totalAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"paidAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"balance":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"issueDate":{"type":"string"},"createdAt":{"type":"string"},"fiscalDocumentId":{"type":"string","nullable":true,"description":"A nota que gerou a conta a receber"},"receivedDocumentId":{"type":"string","nullable":true,"description":"A nota do fornecedor (DF-e)"},"installments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"integer"},"dueDate":{"type":"string"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"paidAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"balance":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"status":{"type":"string"},"derivedStatus":{"type":"string"},"daysOverdue":{"type":"integer"},"dueDatePending":{"type":"boolean"},"settlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","description":"PRINCIPAL alocado à parcela — é o que abate a conta"},"interestAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"fineAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"discountAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"effectiveAmount":{"type":"string","description":"O que de fato entrou/saiu — bate com o extrato"},"date":{"type":"string"},"source":{"type":"string","description":"MANUAL | AUTO"},"reversedAt":{"type":"string","nullable":true,"description":"Não-nulo = ESTORNADA. Fica no histórico e fora de toda soma."}},"required":["id","amount","interestAmount","fineAmount","discountAmount","effectiveAmount","date","source","reversedAt"],"additionalProperties":false}}},"required":["id","sequence","dueDate","amount","paidAmount","balance","status","derivedStatus","daysOverdue","dueDatePending","settlements"],"additionalProperties":false}}},"required":["id","kind","status","origin","description","counterpartyName","counterpartyDocument","clientId","categoryId","categoryName","totalAmount","paidAmount","balance","issueDate","createdAt","fiscalDocumentId","receivedDocumentId","installments"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/summary":{"get":{"summary":"Totais em aberto e aging","tags":["Financeiro"],"description":"Mesma fonte dos cards da tela. As faixas de aging são disjuntas e somam `totalAberto − aConfirmar`.","parameters":[{"schema":{"type":"string","enum":["RECEIVABLE","PAYABLE"]},"in":"query","name":"kind","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"vencidas":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"venceHoje":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"proximos7":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"totalAberto":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"aConfirmar":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false,"description":"Em aberto esperando alguém informar o vencimento. Fica FORA de `vencidas` e do aging, mas DENTRO de `totalAberto` — a dívida existe, o que falta é a data."},"aging":{"type":"object","properties":{"aVencer":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"d1a30":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"d31a60":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"d61a90":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false},"d91mais":{"type":"object","properties":{"valor":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"quantidade":{"type":"integer"}},"required":["valor","quantidade"],"additionalProperties":false}},"required":["aVencer","d1a30","d31a60","d61a90","d91mais"],"additionalProperties":false,"description":"Faixas DISJUNTAS: a soma delas fecha com `totalAberto − aConfirmar`, não com o total."}},"required":["vencidas","venceHoje","proximos7","totalAberto","aConfirmar","aging"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/titles/{id}":{"get":{"summary":"Ficha completa de um título","tags":["Financeiro"],"description":"Traz as parcelas e o histórico de baixas, INCLUSIVE as estornadas (`reversedAt` preenchido). Estornada é histórico e não entra em soma.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do título"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"origin":{"type":"string"},"description":{"type":"string"},"counterpartyName":{"type":"string","nullable":true},"counterpartyDocument":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"categoryId":{"type":"string","nullable":true},"categoryName":{"type":"string","nullable":true},"totalAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"paidAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"balance":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"issueDate":{"type":"string"},"createdAt":{"type":"string"},"fiscalDocumentId":{"type":"string","nullable":true,"description":"A nota que gerou a conta a receber"},"receivedDocumentId":{"type":"string","nullable":true,"description":"A nota do fornecedor (DF-e)"},"installments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"integer"},"dueDate":{"type":"string"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"paidAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"balance":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"status":{"type":"string"},"derivedStatus":{"type":"string"},"daysOverdue":{"type":"integer"},"dueDatePending":{"type":"boolean"},"settlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","description":"PRINCIPAL alocado à parcela — é o que abate a conta"},"interestAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"fineAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"discountAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"effectiveAmount":{"type":"string","description":"O que de fato entrou/saiu — bate com o extrato"},"date":{"type":"string"},"source":{"type":"string","description":"MANUAL | AUTO"},"reversedAt":{"type":"string","nullable":true,"description":"Não-nulo = ESTORNADA. Fica no histórico e fora de toda soma."}},"required":["id","amount","interestAmount","fineAmount","discountAmount","effectiveAmount","date","source","reversedAt"],"additionalProperties":false}}},"required":["id","sequence","dueDate","amount","paidAmount","balance","status","derivedStatus","daysOverdue","dueDatePending","settlements"],"additionalProperties":false}}},"required":["id","kind","status","origin","description","counterpartyName","counterpartyDocument","clientId","categoryId","categoryName","totalAmount","paidAmount","balance","issueDate","createdAt","fiscalDocumentId","receivedDocumentId","installments"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Cancela um título","tags":["Financeiro"],"description":"Cancela o título e suas parcelas. Não apaga: título cancelado continua consultável pelo id.","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/installments/{id}/settlements":{"post":{"summary":"Registra uma baixa na parcela","tags":["Financeiro"],"description":"`amount` é o PRINCIPAL — o que abate a conta. Juros e multa vão nos campos próprios e não abatem o saldo.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"PRINCIPAL alocado à parcela — juros e multa têm campo próprio e NÃO entram aqui. Menor que o saldo deixa a parcela PARTIALLY_PAID, que é caminho normal."},"date":{"type":"string","description":"Data da baixa (YYYY-MM-DD)"},"interestAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"fineAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"discountAmount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["amount","date"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da PARCELA"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"settlementId":{"type":"string"},"installmentId":{"type":"string"},"status":{"type":"string","description":"Situação da parcela após a baixa"}},"required":["settlementId","installmentId","status"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/settlements/{id}":{"delete":{"summary":"Estorna uma baixa","tags":["Financeiro"],"description":"Estorno é soft delete: a baixa continua visível na ficha, marcada, e fora de toda soma. A parcela volta a OPEN ou PARTIALLY_PAID conforme o que sobrou.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID da BAIXA"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"installmentId":{"type":"string"},"status":{"type":"string"}},"required":["installmentId","status"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/receivables/overdue":{"get":{"summary":"Contas a receber vencidas, da mais antiga para a mais nova","tags":["Financeiro"],"description":"Ordem de COBRANÇA: a mais velha é a que corre risco de virar perda. `total` soma TODAS as vencidas mesmo quando a lista vem truncada por `limite`.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limite","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"string","description":"Soma de TODAS as vencidas, não só das listadas"},"quantidade":{"type":"integer"},"contas":{"type":"array","items":{"type":"object","properties":{"cliente":{"type":"string"},"descricao":{"type":"string"},"vencimento":{"type":"string"},"diasEmAtraso":{"type":"integer"},"saldo":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["cliente","descricao","vencimento","diasEmAtraso","saldo"],"additionalProperties":false}}},"required":["total","quantidade","contas"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/receivables/delinquent-clients":{"get":{"summary":"Quem mais deve, agrupado por cliente","tags":["Financeiro"],"description":"Agrupa pelo DOCUMENTO quando existe, pelo nome quando não — o mesmo cliente cadastrado com duas grafias viraria dois devedores.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limite","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"cliente":{"type":"string"},"documento":{"type":"string","nullable":true},"emAtraso":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"contas":{"type":"integer"},"maiorAtrasoEmDias":{"type":"integer"}},"required":["cliente","documento","emAtraso","contas","maiorAtrasoEmDias"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/finance/cashflow-projection":{"get":{"summary":"Projeção de caixa por vencimento","tags":["Financeiro"],"description":"NÃO inclui saldo bancário (isso é Open Finance, capacidade separada) e o que já venceu vem SEPARADO, nunca somado ao previsto: assumir que o inadimplente paga é a hipótese otimista que a tela também recusa. Parcela sem vencimento confirmado fica de fora.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":365},"in":"query","name":"dias","required":false,"description":"Horizonte. Default: 30."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"dias":{"type":"integer"},"aReceber":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"aPagar":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"resultadoPrevisto":{"type":"string","description":"aReceber − aPagar no horizonte"},"vencidoNaoRecebido":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"vencidoNaoPago":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["dias","aReceber","aPagar","resultadoPrevisto","vencidoNaoRecebido","vencidoNaoPago"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-templates":{"get":{"summary":"Lista os templates fiscais visíveis pela empresa","tags":["Templates"],"description":"Retorna os templates da empresa + do tenant + da plataforma (campo `source`). Use o `id` como `templateId` em POST /v1/fiscal-documents.","parameters":[{"schema":{"type":"string","enum":["NFE","NFSE"]},"in":"query","name":"type","required":false,"description":"Filtra por modelo (NFE/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"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um template fiscal da empresa","tags":["Templates"],"description":"Cria um template no escopo da empresa (source=company). O `id` retornado é usável como `templateId` ao criar documentos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome do template"},"type":{"type":"string","enum":["NFE","NFSE"],"description":"Modelo fiscal (NFE ou NFSE)"},"operationNature":{"type":"string","nullable":true,"description":"Natureza da operação (NF-e). Ex: 'Venda de mercadoria'."},"operationNatureCode":{"type":"string","nullable":true,"description":"Código da natureza da operação (NFS-e, 1–8)"},"cfop":{"type":"string","nullable":true,"description":"CFOP padrão (NF-e)"},"icmsOrigin":{"type":"string","nullable":true,"description":"Origem da mercadoria (NF-e)"},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS (NF-e)"},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%) (NF-e)"},"icmsBenefitCode":{"type":"string","nullable":true,"description":"Código de benefício fiscal"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Viaja JUNTO com `rtcCClassTrib`: são os 3 primeiros dígitos dele, e em branco é derivado dele."},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). Enviar qualquer um dos dois grava o PAR; omitir os dois não mexe no gravado."},"serviceListItem":{"type":"string","nullable":true,"description":"Item da LC 116 (NFS-e)"},"serviceDescription":{"type":"string","nullable":true,"description":"Descrição padrão (NFS-e)"},"cnae":{"type":"string","nullable":true,"description":"CNAE do serviço (NFS-e)"},"municipalServiceCode":{"type":"string","nullable":true,"description":"Código de tributação no município (NFS-e)"},"nationalServiceCode":{"type":"string","nullable":true,"description":"Código de serviço nacional / cTribNac (NFS-e)"},"nbs":{"type":"string","nullable":true,"description":"Código NBS (NFS-e)"},"additionalInfo":{"type":"string","nullable":true,"description":"Informações complementares"},"sortOrder":{"type":"integer","nullable":true,"description":"Ordem de exibição"},"isDefault":{"type":"boolean","nullable":true,"description":"Template padrão do tipo (só um por empresa/tipo)"},"isActive":{"type":"boolean","nullable":true}},"required":["name","type"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-templates/{id}":{"get":{"summary":"Detalha um template fiscal visível pela empresa","tags":["Templates"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do template"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza um template fiscal da empresa","tags":["Templates"],"description":"Só templates da própria empresa (source=company). Os de tenant/plataforma são somente-leitura → 404.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome do template"},"type":{"type":"string","enum":["NFE","NFSE"],"description":"Modelo fiscal (NFE ou NFSE)"},"operationNature":{"type":"string","nullable":true,"description":"Natureza da operação (NF-e). Ex: 'Venda de mercadoria'."},"operationNatureCode":{"type":"string","nullable":true,"description":"Código da natureza da operação (NFS-e, 1–8)"},"cfop":{"type":"string","nullable":true,"description":"CFOP padrão (NF-e)"},"icmsOrigin":{"type":"string","nullable":true,"description":"Origem da mercadoria (NF-e)"},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS (NF-e)"},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%) (NF-e)"},"icmsBenefitCode":{"type":"string","nullable":true,"description":"Código de benefício fiscal"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Viaja JUNTO com `rtcCClassTrib`: são os 3 primeiros dígitos dele, e em branco é derivado dele."},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). Enviar qualquer um dos dois grava o PAR; omitir os dois não mexe no gravado."},"serviceListItem":{"type":"string","nullable":true,"description":"Item da LC 116 (NFS-e)"},"serviceDescription":{"type":"string","nullable":true,"description":"Descrição padrão (NFS-e)"},"cnae":{"type":"string","nullable":true,"description":"CNAE do serviço (NFS-e)"},"municipalServiceCode":{"type":"string","nullable":true,"description":"Código de tributação no município (NFS-e)"},"nationalServiceCode":{"type":"string","nullable":true,"description":"Código de serviço nacional / cTribNac (NFS-e)"},"nbs":{"type":"string","nullable":true,"description":"Código NBS (NFS-e)"},"additionalInfo":{"type":"string","nullable":true,"description":"Informações complementares"},"sortOrder":{"type":"integer","nullable":true,"description":"Ordem de exibição"},"isDefault":{"type":"boolean","nullable":true,"description":"Template padrão do tipo (só um por empresa/tipo)"},"isActive":{"type":"boolean","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do template"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"NFE | NFSE"},"source":{"type":"string","description":"company | tenant | system (origem do template)"},"operationNature":{"type":"string","nullable":true},"operationNatureCode":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"icmsOrigin":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true},"icmsModBc":{"type":"string","nullable":true},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota de ICMS (decimal string)"},"icmsBenefitCode":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"rtcCClassTrib":{"type":"string","nullable":true},"serviceListItem":{"type":"string","nullable":true},"serviceDescription":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nationalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","name","type","source","operationNature","operationNatureCode","cfop","icmsOrigin","icmsCst","icmsModBc","icmsRate","icmsBenefitCode","rtcCst","rtcCClassTrib","serviceListItem","serviceDescription","cnae","municipalServiceCode","nationalServiceCode","nbs","additionalInfo","sortOrder","isDefault","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Remove um template fiscal da empresa","tags":["Templates"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do template"}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/gnre":{"get":{"summary":"GNRE da nota: o que é devido, as guias e a cota","tags":["GNRE"],"description":"Apuração pela regra sobre o XML AUTORIZADO da NF-e (DIFAL, FCP e ICMS-ST para outra UF) + as guias já geradas + a cota do mês. A apuração responde mesmo sem o módulo (`moduleEnabled: false`). Nota que não é NF-e autorizada responde 422 `not_authorized_nfe`. Escopo `documents:read`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"fiscalDocumentId":{"type":"string"},"moduleEnabled":{"type":"boolean","description":"A empresa tem o módulo GNRE. Sem ele a apuração continua sendo devolvida (é grátis), mas gerar a guia responde 403 `feature_not_enabled`."},"autoGenerate":{"type":"boolean","description":"Configurações → NF-e: gerar a GNRE automaticamente na autorização"},"assessment":{"type":"object","properties":{"due":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["DIFAL","FCP","ST","FCP_ST"],"description":"O que a guia recolhe"},"ufFavorecida":{"type":"string"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["kind","ufFavorecida","amount"],"additionalProperties":false},"description":"O que a nota exige recolher, pela regra sobre o XML autorizado"},"total":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"noGuideReason":{"type":"string","enum":["INTERNA","EXPORTACAO","ENTRADA","DEVOLUCAO","SEM_ICMS_POR_OPERACAO","INSCRITO_NA_UF","SEM_VALOR","SEM_DESTINATARIO","NOTA_CANCELADA"],"description":"Por que a nota NÃO exige guia. Distingue \"não é devida\" de \"não rodou\" — o texto legível vem em `noGuideMessage`.","nullable":true},"noGuideMessage":{"type":"string","nullable":true}},"required":["due","total","noGuideReason","noGuideMessage"],"additionalProperties":false},"guides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fiscalDocumentId":{"type":"string"},"status":{"type":"string","enum":["PENDING","SENT","ISSUED","REJECTED","BLOCKED","QUOTA_EXCEEDED","CANCELED"],"description":"PENDING (devida, ainda não enviada ou aguardando nova tentativa) · SENT (lote recebido pelo portal, resultado a ler) · ISSUED (emitida: linha digitável e código de barras disponíveis) · REJECTED (recusada pelo portal ou pela UF — motivo em `rejectionReason`) · BLOCKED (falta dado que não sabemos preencher) · QUOTA_EXCEEDED (cota mensal do plano esgotada — a NOTA segue normal) · CANCELED (nota cancelada)"},"environment":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"]},"ufFavorecida":{"type":"string","description":"UF que recebe o recolhimento"},"receita":{"type":"string","description":"Código de receita do Portal GNRE (ex.: 100102 = DIFAL)"},"receitaDescription":{"type":"string","nullable":true,"description":"Rótulo da receita, quando conhecido"},"kind":{"type":"string","enum":["DIFAL","FCP","ST","FCP_ST"],"description":"O que a guia recolhe"},"principal":{"type":"string","description":"Valor principal"},"fcp":{"type":"string","description":"FCP levado na MESMA guia, quando a UF pede (senão 0.00)"},"total":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"dueDate":{"type":"string","description":"Vencimento AAAA-MM-DD"},"origin":{"type":"string","description":"AUTO (na autorização da nota) | MANUAL (botão ou API)"},"receiptNumber":{"type":"string","nullable":true,"description":"Recibo do lote no portal"},"digitableLine":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"pixCopiaECola":{"type":"string","nullable":true,"description":"Pix \"copia e cola\" da guia, quando a UF aceita Pix (senão null)"},"nossoNumero":{"type":"string","nullable":true},"controlNumber":{"type":"string","nullable":true},"rejectionCode":{"type":"string","nullable":true},"rejectionField":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"attempts":{"type":"integer"},"nextAttemptAt":{"type":"string","nullable":true},"issuedAt":{"type":"string","nullable":true},"canceledAt":{"type":"string","nullable":true},"payableTitleId":{"type":"string","nullable":true,"description":"Conta a pagar gerada no módulo financeiro"},"pdfAvailable":{"type":"boolean","description":"O PDF sai em `GET /v1/gnre/{id}/pdf` (guia emitida)"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fiscalDocumentId","status","environment","ufFavorecida","receita","receitaDescription","kind","principal","fcp","total","dueDate","origin","receiptNumber","digitableLine","barcode","pixCopiaECola","nossoNumero","controlNumber","rejectionCode","rejectionField","rejectionReason","attempts","nextAttemptAt","issuedAt","canceledAt","payableTitleId","pdfAvailable","createdAt","updatedAt"],"additionalProperties":false}},"quota":{"type":"object","properties":{"month":{"type":"string","description":"Mês da cota (horário de Brasília)"},"limit":{"type":"integer","nullable":true,"description":"Guias de PRODUÇÃO por mês incluídas no plano. null = sem plano/sem cota definida"},"used":{"type":"integer","description":"Emitidas no mês + as que estão a caminho (SENT)"},"extraPrice":{"type":"string","nullable":true,"description":"Preço de cada guia além da cota, quando o plano cobra"}},"required":["month","limit","used","extraPrice"],"additionalProperties":false}},"required":["fiscalDocumentId","moduleEnabled","autoGenerate","assessment","guides","quota"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Gera (ou regera) as guias GNRE da nota","tags":["GNRE"],"description":"Idempotente: guia ISSUED/SENT não é tocada; PENDING, REJECTED, BLOCKED e QUOTA_EXCEEDED são refeitas. O resultado do portal sai em ≥ 30 s e é consultado sozinho — acompanhe por `GET …/gnre`, pelo webhook `GNRE_ISSUED`/`GNRE_REJECTED` ou force com `POST …/gnre/refresh`. Falha do portal fica gravada na guia, não volta como erro. Exige o módulo GNRE (403 `feature_not_enabled`) e o certificado A1 (422 `certificate_unavailable`). Escopo `documents:write`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"noGuideReason":{"type":"string","enum":["INTERNA","EXPORTACAO","ENTRADA","DEVOLUCAO","SEM_ICMS_POR_OPERACAO","INSCRITO_NA_UF","SEM_VALOR","SEM_DESTINATARIO","NOTA_CANCELADA"],"description":"Preenchido quando a nota não exige guia","nullable":true},"noGuideMessage":{"type":"string","nullable":true},"sent":{"type":"integer","description":"Guias enviadas ao portal neste pedido (resultado em ≥ 30 s)"},"blocked":{"type":"integer","description":"Faltou dado que não sabemos preencher (status BLOCKED)"},"quotaExceeded":{"type":"integer","description":"Ficaram fora pela cota do plano (QUOTA_EXCEEDED)"},"pending":{"type":"integer","description":"Voltaram a PENDING por falha de comunicação (retentadas sozinhas)"},"receiptNumber":{"type":"string","nullable":true}},"required":["noGuideReason","noGuideMessage","sent","blocked","quotaExceeded","pending","receiptNumber"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/fiscal-documents/{id}/gnre/refresh":{"post":{"summary":"Consulta agora o resultado dos lotes GNRE enviados da nota","tags":["GNRE"],"description":"Lê no portal o resultado das guias em SENT (emitidas ganham linha digitável; rejeitadas, o motivo). Seguro de chamar a qualquer momento — antes dos 30 s o portal ainda está processando (`processing: true`). Escopo `documents:write`: muda o estado das guias.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"processing":{"type":"boolean","description":"Algum lote ainda em processamento no portal — consulte de novo"},"issued":{"type":"integer"},"rejected":{"type":"integer"},"pending":{"type":"integer"}},"required":["processing","issued","rejected","pending"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/gnre":{"get":{"summary":"Lista as guias GNRE da empresa","tags":["GNRE"],"description":"Da mais recente para a mais antiga, com filtro por status, UF favorecida e ambiente (padrão PRODUCTION, como a listagem de notas). Sem o módulo GNRE: 403 `feature_not_enabled` — nunca lista vazia. Escopo `documents:read`.","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":["PENDING","SENT","ISSUED","REJECTED","BLOCKED","QUOTA_EXCEEDED","CANCELED"]},"in":"query","name":"status","required":false,"description":"PENDING (devida, ainda não enviada ou aguardando nova tentativa) · SENT (lote recebido pelo portal, resultado a ler) · ISSUED (emitida: linha digitável e código de barras disponíveis) · REJECTED (recusada pelo portal ou pela UF — motivo em `rejectionReason`) · BLOCKED (falta dado que não sabemos preencher) · QUOTA_EXCEEDED (cota mensal do plano esgotada — a NOTA segue normal) · CANCELED (nota cancelada)"},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"in":"query","name":"uf","required":false,"description":"UF favorecida (sigla, ex.: SP)"},{"schema":{"type":"string","enum":["PRODUCTION","HOMOLOGATION","ALL"],"default":"PRODUCTION"},"in":"query","name":"environment","required":false,"description":"Ambiente das guias (o da nota). Padrão PRODUCTION — guia de homologação só aparece com HOMOLOGATION ou ALL."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fiscalDocumentId":{"type":"string"},"status":{"type":"string","enum":["PENDING","SENT","ISSUED","REJECTED","BLOCKED","QUOTA_EXCEEDED","CANCELED"],"description":"PENDING (devida, ainda não enviada ou aguardando nova tentativa) · SENT (lote recebido pelo portal, resultado a ler) · ISSUED (emitida: linha digitável e código de barras disponíveis) · REJECTED (recusada pelo portal ou pela UF — motivo em `rejectionReason`) · BLOCKED (falta dado que não sabemos preencher) · QUOTA_EXCEEDED (cota mensal do plano esgotada — a NOTA segue normal) · CANCELED (nota cancelada)"},"environment":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"]},"ufFavorecida":{"type":"string","description":"UF que recebe o recolhimento"},"receita":{"type":"string","description":"Código de receita do Portal GNRE (ex.: 100102 = DIFAL)"},"receitaDescription":{"type":"string","nullable":true,"description":"Rótulo da receita, quando conhecido"},"kind":{"type":"string","enum":["DIFAL","FCP","ST","FCP_ST"],"description":"O que a guia recolhe"},"principal":{"type":"string","description":"Valor principal"},"fcp":{"type":"string","description":"FCP levado na MESMA guia, quando a UF pede (senão 0.00)"},"total":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"dueDate":{"type":"string","description":"Vencimento AAAA-MM-DD"},"origin":{"type":"string","description":"AUTO (na autorização da nota) | MANUAL (botão ou API)"},"receiptNumber":{"type":"string","nullable":true,"description":"Recibo do lote no portal"},"digitableLine":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"pixCopiaECola":{"type":"string","nullable":true,"description":"Pix \"copia e cola\" da guia, quando a UF aceita Pix (senão null)"},"nossoNumero":{"type":"string","nullable":true},"controlNumber":{"type":"string","nullable":true},"rejectionCode":{"type":"string","nullable":true},"rejectionField":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"attempts":{"type":"integer"},"nextAttemptAt":{"type":"string","nullable":true},"issuedAt":{"type":"string","nullable":true},"canceledAt":{"type":"string","nullable":true},"payableTitleId":{"type":"string","nullable":true,"description":"Conta a pagar gerada no módulo financeiro"},"pdfAvailable":{"type":"boolean","description":"O PDF sai em `GET /v1/gnre/{id}/pdf` (guia emitida)"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"fiscalDocument":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","nullable":true},"series":{"type":"integer","nullable":true},"clientName":{"type":"string","nullable":true}},"required":["id","number","series","clientName"],"additionalProperties":false}},"required":["id","fiscalDocumentId","status","environment","ufFavorecida","receita","receitaDescription","kind","principal","fcp","total","dueDate","origin","receiptNumber","digitableLine","barcode","pixCopiaECola","nossoNumero","controlNumber","rejectionCode","rejectionField","rejectionReason","attempts","nextAttemptAt","issuedAt","canceledAt","payableTitleId","pdfAvailable","createdAt","updatedAt","fiscalDocument"],"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},"quota":{"type":"object","properties":{"month":{"type":"string","description":"Mês da cota (horário de Brasília)"},"limit":{"type":"integer","nullable":true,"description":"Guias de PRODUÇÃO por mês incluídas no plano. null = sem plano/sem cota definida"},"used":{"type":"integer","description":"Emitidas no mês + as que estão a caminho (SENT)"},"extraPrice":{"type":"string","nullable":true,"description":"Preço de cada guia além da cota, quando o plano cobra"}},"required":["month","limit","used","extraPrice"],"additionalProperties":false}},"required":["data","meta","quota"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/gnre/{id}/pdf":{"get":{"summary":"Baixa o PDF da guia GNRE","tags":["GNRE"],"description":"Só para guia emitida (ou cancelada depois de emitida); as demais respondem 404 `guide_not_found`. Use `?download=true` para forçar download. Resposta: `application/pdf`. Escopo `documents:read`.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"download","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/products":{"get":{"summary":"Lista os produtos da empresa","tags":["Products"],"description":"Cada produto vem com a configuração de NF-e (tributação própria incluída) e de NFS-e.","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":"search","required":false,"description":"Busca por nome ou código"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"PRODUTOR | AFILIADO | COPRODUTOR"},"salePrice":{"type":"string","description":"Decimal como string"},"emissionModel":{"type":"string","description":"NFE | NFSE | SPLIT"},"warranty":{"type":"integer","nullable":true},"nfePercentage":{"type":"string","nullable":true},"nfsePercentage":{"type":"string","nullable":true},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true},"fiscalDescription":{"type":"string","nullable":true},"commercialUnit":{"type":"string"},"taxUnit":{"type":"string"},"taxUnitExport":{"type":"string"},"internalCfop":{"type":"string","nullable":true},"interstateContributor":{"type":"string","nullable":true},"interstateNonContributor":{"type":"string","nullable":true},"internationalCfop":{"type":"string","nullable":true},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true,"description":"7 dígitos, sem pontos"},"taxRuleId":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS"},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS (%) (decimal como string)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%) (decimal como string)"},"icmsStModBc":{"type":"string","nullable":true,"description":"4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%) (decimal como string)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%) (decimal como string)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%) (decimal como string)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Crédito do Simples (%) (decimal como string)"},"icmsDesonValue":{"type":"string","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) (decimal como string)"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS)"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — abate o total da nota"},"icmsDeferralRate":{"type":"string","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51 (decimal como string)"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>)"},"icmsStRetBase":{"type":"string","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$) (decimal como string)"},"icmsStRetRate":{"type":"string","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %) (decimal como string)"},"icmsSubstitutoValue":{"type":"string","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional (decimal como string)"},"icmsStRetValue":{"type":"string","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$) (decimal como string)"},"fcpStRetBase":{"type":"string","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$) (decimal como string)"},"fcpStRetRate":{"type":"string","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %) (decimal como string)"},"fcpStRetValue":{"type":"string","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$) (decimal como string)"},"pisCst":{"type":"string","nullable":true},"pisRate":{"type":"string","nullable":true,"description":"Alíquota do PIS (%) (decimal como string)"},"cofinsCst":{"type":"string","nullable":true},"cofinsRate":{"type":"string","nullable":true,"description":"Alíquota da COFINS (%) (decimal como string)"},"ipiCst":{"type":"string","nullable":true},"ipiRate":{"type":"string","nullable":true,"description":"Alíquota do IPI (%) (decimal como string)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (6 dígitos)"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos)"}},"required":["barCode","fiscalDescription","commercialUnit","taxUnit","taxUnitExport","internalCfop","interstateContributor","interstateNonContributor","internationalCfop","ncm","cest","taxRuleId","additionalInfo","icmsCst","icmsRate","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","icmsCBenef","icmsStRetBase","icmsStRetRate","icmsSubstitutoValue","icmsStRetValue","fcpStRetBase","fcpStRetRate","fcpStRetValue","pisCst","pisRate","cofinsCst","cofinsRate","ipiCst","ipiRate","rtcCClassTrib","rtcCst"],"additionalProperties":false,"nullable":true},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string"},"serviceListItem":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"taxRuleId":{"type":"string","nullable":true},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"string","nullable":true,"description":"Alíquota do ISS (%) (decimal como string)"},"federalTax":{"type":"string"},"stateTax":{"type":"string"},"municipalTax":{"type":"string"}},"required":["serviceDescription","serviceListItem","municipalServiceCode","nbs","cnae","taxRuleId","useSpecificTaxation","useIbpt","issRate","federalTax","stateTax","municipalTax"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","code","name","profile","salePrice","emissionModel","warranty","nfePercentage","nfsePercentage","nfeConfig","nfseConfig","createdAt","updatedAt"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um produto (com a tributação própria)","tags":["Products"],"description":"Na nota, cada campo de imposto vem, do mais específico ao mais genérico: do ITEM (o que a nota manda sempre prevalece) → da Regra Fiscal do produto (a do item/documento via `taxRuleId`, senão a vinculada ao produto; casada por UF, tipo de cliente e CFOP da operação) → da tributação própria do PRODUTO → do template fiscal → das regras padrão da empresa. A tributação própria é o padrão do produto em qualquer UF; ICMS-ST que muda por estado fica melhor na Regra Fiscal. Recusas (422): CEST fora dos 7 dígitos (`invalid_cest`), CFOP no campo errado (`invalid_cfop` — interno 5xxx, interestadual 6xxx, exportação 7xxx), regra de outra empresa ou de outro modelo (`invalid_tax_rule`), tributação que a emissão recusaria — CST da tabela errada para o regime da empresa, MVA/alíquota de ST ou crédito do Simples faltando, percentual fora da faixa (`invalid_taxation`) — e código repetido (`duplicate_code`). Os CFOPs interestaduais omitidos são sugeridos a partir do interno e voltam na resposta.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Nome do produto"},"code":{"type":"string","minLength":1,"description":"Código/SKU — único na empresa"},"profile":{"type":"string","enum":["PRODUTOR","AFILIADO","COPRODUTOR"],"default":"PRODUTOR","description":"Seu papel na venda: PRODUTOR (default) emite a nota ao comprador; AFILIADO/COPRODUTOR seguem a apuração de comissão."},"salePrice":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Preço de venda"},"emissionModel":{"type":"string","enum":["NFE","NFSE","SPLIT"],"default":"NFE","description":"NFE (default), NFSE ou SPLIT (metade mercadoria + metade serviço)"},"warranty":{"type":"integer","minimum":0,"nullable":true,"description":"Garantia em dias"},"nfePercentage":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Parte da venda na NF-e no modo SPLIT (%)"},"nfsePercentage":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Parte da venda na NFS-e no modo SPLIT (%)"},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true,"description":"GTIN/EAN (<cEAN>)"},"fiscalDescription":{"type":"string","nullable":true,"description":"Descrição na nota (<xProd>). Vazio = nome do produto."},"commercialUnit":{"type":"string","minLength":1,"description":"Unidade comercial. Default na criação: 'UN - UNIDADE'."},"taxUnit":{"type":"string","minLength":1,"description":"Unidade tributável. Default na criação: 'UN - UNIDADE'."},"taxUnitExport":{"type":"string","minLength":1,"description":"Unidade tributável na exportação. Default na criação: 'KG - QUILOGRAMA'."},"internalCfop":{"type":"string","nullable":true,"description":"CFOP dentro do estado — começa com 5 (ex.: 5102)."},"interstateContributor":{"type":"string","nullable":true,"description":"CFOP interestadual para contribuinte de ICMS — começa com 6. OMITIDO e sem valor gravado, é PREENCHIDO a partir do interno (5102 → 6102) e volta na resposta para você conferir ou trocar. `null` explícito deixa em branco."},"interstateNonContributor":{"type":"string","nullable":true,"description":"CFOP interestadual para NÃO contribuinte — começa com 6. Omitido e sem valor gravado, é preenchido a partir do interno (5102 → 6108, venda a consumidor final de outra UF). `null` explícito deixa em branco."},"internationalCfop":{"type":"string","nullable":true,"description":"CFOP de exportação — começa com 7 (ex.: 7102)."},"ncm":{"type":"string","nullable":true,"description":"NCM (8 dígitos)"},"cest":{"type":"string","nullable":true,"description":"CEST — 7 dígitos, pontos opcionais ('03.006.00'). Obrigatório na emissão quando o ICMS tem ST (CST 10/30/70, CSOSN 201/202/203): sem ele a SEFAZ rejeita (806)."},"taxRuleId":{"type":"string","nullable":true,"description":"Regra Fiscal do produto (GET /v1/tax-rules, modelo NFE). Vale quando a nota não indica regra própria."},"additionalInfo":{"type":"string","nullable":true,"description":"Informações adicionais do item (<infAdProd>)"},"icmsCst":{"type":"string","nullable":true,"description":"CST (Regime Normal) ou CSOSN (Simples Nacional/MEI) do ICMS. Precisa ser da tabela do regime da empresa — CST 00 numa empresa do Simples é recusado com 422, porque a SEFAZ o recusaria (590)."},"icmsRate":{"type":"number","nullable":true,"description":"Alíquota do ICMS próprio (%)"},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — exigida nos CST 20 e 70; ignorada nos demais"},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação. Exigida nos CST 10/30/70 e CSOSN 201/202/203."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%) — exigida na modalidade 4"},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%) — opcional"},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota interna do ICMS-ST no destino (%) — exigida com ST"},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — exigida nos CSOSN 101 e 201"},"icmsDesonValue":{"type":"number","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS) — a tabela aceita valores DIFERENTES por CST"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — verdadeiro faz o desonerado ABATER o total da nota (vNF)"},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51. 100 = diferimento integral"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>, ex.: RS052001) — 8 ou 10 caracteres, ou \"SEM CBENEF\". Acompanha o icmsCst DESTE produto e é descartado sem ele. Vários estados rejeitam (930) CST com benefício (20, 30, 40, 41, 51, 70, 90…) sem o código."},"icmsStRetBase":{"type":"number","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$)"},"icmsStRetRate":{"type":"number","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %)"},"icmsSubstitutoValue":{"type":"number","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional"},"icmsStRetValue":{"type":"number","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$)"},"fcpStRetBase":{"type":"number","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$)"},"fcpStRetRate":{"type":"number","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %)"},"fcpStRetValue":{"type":"number","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$)"},"pisCst":{"type":"string","nullable":true,"description":"CST do PIS"},"pisRate":{"type":"number","nullable":true,"description":"Alíquota do PIS (%)"},"cofinsCst":{"type":"string","nullable":true,"description":"CST da COFINS"},"cofinsRate":{"type":"number","nullable":true,"description":"Alíquota da COFINS (%)"},"ipiCst":{"type":"string","nullable":true,"description":"CST do IPI"},"ipiRate":{"type":"number","nullable":true,"description":"Alíquota do IPI (%)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). O CST são os 3 primeiros dígitos dela e é derivado quando omitido. 🔴 O código NÃO é conferido contra a tabela oficial (ela é publicada fora do XSD, que valida só o formato): um código errado é ACEITO pela SEFAZ e a nota sai declarando outra classificação."},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Omita: ele é derivado do cClassTrib. Informado e divergente, é descartado em favor do derivado — o par divergente é rejeitado."}},"additionalProperties":false,"description":"Configuração de NF-e do produto, com a tributação própria. Na nota, cada campo de imposto vem, do mais específico ao mais genérico: do ITEM (o que a nota manda sempre prevalece) → da Regra Fiscal do produto (a do item/documento via `taxRuleId`, senão a vinculada ao produto; casada por UF, tipo de cliente e CFOP da operação) → da tributação própria do PRODUTO → do template fiscal → das regras padrão da empresa. A tributação própria é o padrão do produto em qualquer UF; ICMS-ST que muda por estado fica melhor na Regra Fiscal. Parâmetro que o código de ICMS não usa é gravado nulo (ex.: MVA num CSOSN 102), e alíquota sem o CST dela também.","nullable":true},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string","description":"Discriminação do serviço"},"serviceListItem":{"type":"string","nullable":true,"description":"Item da lista da LC 116 (ex.: 01.05)"},"municipalServiceCode":{"type":"string","nullable":true,"description":"Código de tributação municipal"},"nbs":{"type":"string","nullable":true,"description":"Código NBS (`<cNBS>`, 9 dígitos). Vazio = o padrão da empresa."},"cnae":{"type":"string","nullable":true,"description":"CNAE do serviço. Vazio = o da empresa."},"taxRuleId":{"type":"string","nullable":true,"description":"Regra Fiscal de NFS-e (GET /v1/tax-rules, modelo NFSE)"},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Alíquota do ISS (%) deste serviço. Vazio = a da empresa."},"federalTax":{"type":"number","minimum":0,"maximum":100},"stateTax":{"type":"number","minimum":0,"maximum":100},"municipalTax":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false,"description":"Configuração de NFS-e do produto","nullable":true}},"required":["name","code","salePrice"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"PRODUTOR | AFILIADO | COPRODUTOR"},"salePrice":{"type":"string","description":"Decimal como string"},"emissionModel":{"type":"string","description":"NFE | NFSE | SPLIT"},"warranty":{"type":"integer","nullable":true},"nfePercentage":{"type":"string","nullable":true},"nfsePercentage":{"type":"string","nullable":true},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true},"fiscalDescription":{"type":"string","nullable":true},"commercialUnit":{"type":"string"},"taxUnit":{"type":"string"},"taxUnitExport":{"type":"string"},"internalCfop":{"type":"string","nullable":true},"interstateContributor":{"type":"string","nullable":true},"interstateNonContributor":{"type":"string","nullable":true},"internationalCfop":{"type":"string","nullable":true},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true,"description":"7 dígitos, sem pontos"},"taxRuleId":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS"},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS (%) (decimal como string)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%) (decimal como string)"},"icmsStModBc":{"type":"string","nullable":true,"description":"4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%) (decimal como string)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%) (decimal como string)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%) (decimal como string)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Crédito do Simples (%) (decimal como string)"},"icmsDesonValue":{"type":"string","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) (decimal como string)"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS)"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — abate o total da nota"},"icmsDeferralRate":{"type":"string","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51 (decimal como string)"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>)"},"icmsStRetBase":{"type":"string","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$) (decimal como string)"},"icmsStRetRate":{"type":"string","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %) (decimal como string)"},"icmsSubstitutoValue":{"type":"string","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional (decimal como string)"},"icmsStRetValue":{"type":"string","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$) (decimal como string)"},"fcpStRetBase":{"type":"string","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$) (decimal como string)"},"fcpStRetRate":{"type":"string","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %) (decimal como string)"},"fcpStRetValue":{"type":"string","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$) (decimal como string)"},"pisCst":{"type":"string","nullable":true},"pisRate":{"type":"string","nullable":true,"description":"Alíquota do PIS (%) (decimal como string)"},"cofinsCst":{"type":"string","nullable":true},"cofinsRate":{"type":"string","nullable":true,"description":"Alíquota da COFINS (%) (decimal como string)"},"ipiCst":{"type":"string","nullable":true},"ipiRate":{"type":"string","nullable":true,"description":"Alíquota do IPI (%) (decimal como string)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (6 dígitos)"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos)"}},"required":["barCode","fiscalDescription","commercialUnit","taxUnit","taxUnitExport","internalCfop","interstateContributor","interstateNonContributor","internationalCfop","ncm","cest","taxRuleId","additionalInfo","icmsCst","icmsRate","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","icmsCBenef","icmsStRetBase","icmsStRetRate","icmsSubstitutoValue","icmsStRetValue","fcpStRetBase","fcpStRetRate","fcpStRetValue","pisCst","pisRate","cofinsCst","cofinsRate","ipiCst","ipiRate","rtcCClassTrib","rtcCst"],"additionalProperties":false,"nullable":true},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string"},"serviceListItem":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"taxRuleId":{"type":"string","nullable":true},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"string","nullable":true,"description":"Alíquota do ISS (%) (decimal como string)"},"federalTax":{"type":"string"},"stateTax":{"type":"string"},"municipalTax":{"type":"string"}},"required":["serviceDescription","serviceListItem","municipalServiceCode","nbs","cnae","taxRuleId","useSpecificTaxation","useIbpt","issRate","federalTax","stateTax","municipalTax"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","code","name","profile","salePrice","emissionModel","warranty","nfePercentage","nfsePercentage","nfeConfig","nfseConfig","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/products/{id}":{"get":{"summary":"Detalha um produto","tags":["Products"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do produto"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"PRODUTOR | AFILIADO | COPRODUTOR"},"salePrice":{"type":"string","description":"Decimal como string"},"emissionModel":{"type":"string","description":"NFE | NFSE | SPLIT"},"warranty":{"type":"integer","nullable":true},"nfePercentage":{"type":"string","nullable":true},"nfsePercentage":{"type":"string","nullable":true},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true},"fiscalDescription":{"type":"string","nullable":true},"commercialUnit":{"type":"string"},"taxUnit":{"type":"string"},"taxUnitExport":{"type":"string"},"internalCfop":{"type":"string","nullable":true},"interstateContributor":{"type":"string","nullable":true},"interstateNonContributor":{"type":"string","nullable":true},"internationalCfop":{"type":"string","nullable":true},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true,"description":"7 dígitos, sem pontos"},"taxRuleId":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS"},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS (%) (decimal como string)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%) (decimal como string)"},"icmsStModBc":{"type":"string","nullable":true,"description":"4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%) (decimal como string)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%) (decimal como string)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%) (decimal como string)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Crédito do Simples (%) (decimal como string)"},"icmsDesonValue":{"type":"string","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) (decimal como string)"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS)"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — abate o total da nota"},"icmsDeferralRate":{"type":"string","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51 (decimal como string)"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>)"},"icmsStRetBase":{"type":"string","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$) (decimal como string)"},"icmsStRetRate":{"type":"string","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %) (decimal como string)"},"icmsSubstitutoValue":{"type":"string","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional (decimal como string)"},"icmsStRetValue":{"type":"string","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$) (decimal como string)"},"fcpStRetBase":{"type":"string","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$) (decimal como string)"},"fcpStRetRate":{"type":"string","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %) (decimal como string)"},"fcpStRetValue":{"type":"string","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$) (decimal como string)"},"pisCst":{"type":"string","nullable":true},"pisRate":{"type":"string","nullable":true,"description":"Alíquota do PIS (%) (decimal como string)"},"cofinsCst":{"type":"string","nullable":true},"cofinsRate":{"type":"string","nullable":true,"description":"Alíquota da COFINS (%) (decimal como string)"},"ipiCst":{"type":"string","nullable":true},"ipiRate":{"type":"string","nullable":true,"description":"Alíquota do IPI (%) (decimal como string)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (6 dígitos)"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos)"}},"required":["barCode","fiscalDescription","commercialUnit","taxUnit","taxUnitExport","internalCfop","interstateContributor","interstateNonContributor","internationalCfop","ncm","cest","taxRuleId","additionalInfo","icmsCst","icmsRate","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","icmsCBenef","icmsStRetBase","icmsStRetRate","icmsSubstitutoValue","icmsStRetValue","fcpStRetBase","fcpStRetRate","fcpStRetValue","pisCst","pisRate","cofinsCst","cofinsRate","ipiCst","ipiRate","rtcCClassTrib","rtcCst"],"additionalProperties":false,"nullable":true},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string"},"serviceListItem":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"taxRuleId":{"type":"string","nullable":true},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"string","nullable":true,"description":"Alíquota do ISS (%) (decimal como string)"},"federalTax":{"type":"string"},"stateTax":{"type":"string"},"municipalTax":{"type":"string"}},"required":["serviceDescription","serviceListItem","municipalServiceCode","nbs","cnae","taxRuleId","useSpecificTaxation","useIbpt","issRate","federalTax","stateTax","municipalTax"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","code","name","profile","salePrice","emissionModel","warranty","nfePercentage","nfsePercentage","nfeConfig","nfseConfig","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza um produto (parcial)","tags":["Products"],"description":"Campo não enviado MANTÉM o valor gravado; `null` explícito limpa. Na tributação, os campos enviados são mesclados com os gravados e o RESULTADO é validado — mandar só `pisCst` não apaga o CSOSN do produto, e trocar o CSOSN de 201 para 102 descarta a MVA/ST que o 102 não usa. Na nota, cada campo de imposto vem, do mais específico ao mais genérico: do ITEM (o que a nota manda sempre prevalece) → da Regra Fiscal do produto (a do item/documento via `taxRuleId`, senão a vinculada ao produto; casada por UF, tipo de cliente e CFOP da operação) → da tributação própria do PRODUTO → do template fiscal → das regras padrão da empresa. A tributação própria é o padrão do produto em qualquer UF; ICMS-ST que muda por estado fica melhor na Regra Fiscal. Mesmas recusas (422) da criação.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"profile":{"type":"string","enum":["PRODUTOR","AFILIADO","COPRODUTOR"]},"salePrice":{"type":"number","exclusiveMinimum":true,"minimum":0},"emissionModel":{"type":"string","enum":["NFE","NFSE","SPLIT"]},"warranty":{"type":"integer","minimum":0,"nullable":true},"nfePercentage":{"type":"number","minimum":0,"maximum":100,"nullable":true},"nfsePercentage":{"type":"number","minimum":0,"maximum":100,"nullable":true},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true,"description":"GTIN/EAN (<cEAN>)"},"fiscalDescription":{"type":"string","nullable":true,"description":"Descrição na nota (<xProd>). Vazio = nome do produto."},"commercialUnit":{"type":"string","minLength":1,"description":"Unidade comercial. Default na criação: 'UN - UNIDADE'."},"taxUnit":{"type":"string","minLength":1,"description":"Unidade tributável. Default na criação: 'UN - UNIDADE'."},"taxUnitExport":{"type":"string","minLength":1,"description":"Unidade tributável na exportação. Default na criação: 'KG - QUILOGRAMA'."},"internalCfop":{"type":"string","nullable":true,"description":"CFOP dentro do estado — começa com 5 (ex.: 5102)."},"interstateContributor":{"type":"string","nullable":true,"description":"CFOP interestadual para contribuinte de ICMS — começa com 6. OMITIDO e sem valor gravado, é PREENCHIDO a partir do interno (5102 → 6102) e volta na resposta para você conferir ou trocar. `null` explícito deixa em branco."},"interstateNonContributor":{"type":"string","nullable":true,"description":"CFOP interestadual para NÃO contribuinte — começa com 6. Omitido e sem valor gravado, é preenchido a partir do interno (5102 → 6108, venda a consumidor final de outra UF). `null` explícito deixa em branco."},"internationalCfop":{"type":"string","nullable":true,"description":"CFOP de exportação — começa com 7 (ex.: 7102)."},"ncm":{"type":"string","nullable":true,"description":"NCM (8 dígitos)"},"cest":{"type":"string","nullable":true,"description":"CEST — 7 dígitos, pontos opcionais ('03.006.00'). Obrigatório na emissão quando o ICMS tem ST (CST 10/30/70, CSOSN 201/202/203): sem ele a SEFAZ rejeita (806)."},"taxRuleId":{"type":"string","nullable":true,"description":"Regra Fiscal do produto (GET /v1/tax-rules, modelo NFE). Vale quando a nota não indica regra própria."},"additionalInfo":{"type":"string","nullable":true,"description":"Informações adicionais do item (<infAdProd>)"},"icmsCst":{"type":"string","nullable":true,"description":"CST (Regime Normal) ou CSOSN (Simples Nacional/MEI) do ICMS. Precisa ser da tabela do regime da empresa — CST 00 numa empresa do Simples é recusado com 422, porque a SEFAZ o recusaria (590)."},"icmsRate":{"type":"number","nullable":true,"description":"Alíquota do ICMS próprio (%)"},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — exigida nos CST 20 e 70; ignorada nos demais"},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação. Exigida nos CST 10/30/70 e CSOSN 201/202/203."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%) — exigida na modalidade 4"},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%) — opcional"},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota interna do ICMS-ST no destino (%) — exigida com ST"},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — exigida nos CSOSN 101 e 201"},"icmsDesonValue":{"type":"number","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS) — a tabela aceita valores DIFERENTES por CST"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — verdadeiro faz o desonerado ABATER o total da nota (vNF)"},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51. 100 = diferimento integral"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>, ex.: RS052001) — 8 ou 10 caracteres, ou \"SEM CBENEF\". Acompanha o icmsCst DESTE produto e é descartado sem ele. Vários estados rejeitam (930) CST com benefício (20, 30, 40, 41, 51, 70, 90…) sem o código."},"icmsStRetBase":{"type":"number","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$)"},"icmsStRetRate":{"type":"number","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %)"},"icmsSubstitutoValue":{"type":"number","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional"},"icmsStRetValue":{"type":"number","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$)"},"fcpStRetBase":{"type":"number","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$)"},"fcpStRetRate":{"type":"number","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %)"},"fcpStRetValue":{"type":"number","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$)"},"pisCst":{"type":"string","nullable":true,"description":"CST do PIS"},"pisRate":{"type":"number","nullable":true,"description":"Alíquota do PIS (%)"},"cofinsCst":{"type":"string","nullable":true,"description":"CST da COFINS"},"cofinsRate":{"type":"number","nullable":true,"description":"Alíquota da COFINS (%)"},"ipiCst":{"type":"string","nullable":true,"description":"CST do IPI"},"ipiRate":{"type":"number","nullable":true,"description":"Alíquota do IPI (%)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). O CST são os 3 primeiros dígitos dela e é derivado quando omitido. 🔴 O código NÃO é conferido contra a tabela oficial (ela é publicada fora do XSD, que valida só o formato): um código errado é ACEITO pela SEFAZ e a nota sai declarando outra classificação."},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Omita: ele é derivado do cClassTrib. Informado e divergente, é descartado em favor do derivado — o par divergente é rejeitado."}},"additionalProperties":false,"description":"Configuração de NF-e do produto, com a tributação própria. Na nota, cada campo de imposto vem, do mais específico ao mais genérico: do ITEM (o que a nota manda sempre prevalece) → da Regra Fiscal do produto (a do item/documento via `taxRuleId`, senão a vinculada ao produto; casada por UF, tipo de cliente e CFOP da operação) → da tributação própria do PRODUTO → do template fiscal → das regras padrão da empresa. A tributação própria é o padrão do produto em qualquer UF; ICMS-ST que muda por estado fica melhor na Regra Fiscal. Parâmetro que o código de ICMS não usa é gravado nulo (ex.: MVA num CSOSN 102), e alíquota sem o CST dela também."},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string","description":"Discriminação do serviço"},"serviceListItem":{"type":"string","nullable":true,"description":"Item da lista da LC 116 (ex.: 01.05)"},"municipalServiceCode":{"type":"string","nullable":true,"description":"Código de tributação municipal"},"nbs":{"type":"string","nullable":true,"description":"Código NBS (`<cNBS>`, 9 dígitos). Vazio = o padrão da empresa."},"cnae":{"type":"string","nullable":true,"description":"CNAE do serviço. Vazio = o da empresa."},"taxRuleId":{"type":"string","nullable":true,"description":"Regra Fiscal de NFS-e (GET /v1/tax-rules, modelo NFSE)"},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Alíquota do ISS (%) deste serviço. Vazio = a da empresa."},"federalTax":{"type":"number","minimum":0,"maximum":100},"stateTax":{"type":"number","minimum":0,"maximum":100},"municipalTax":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false,"description":"Configuração de NFS-e do produto"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do produto"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"PRODUTOR | AFILIADO | COPRODUTOR"},"salePrice":{"type":"string","description":"Decimal como string"},"emissionModel":{"type":"string","description":"NFE | NFSE | SPLIT"},"warranty":{"type":"integer","nullable":true},"nfePercentage":{"type":"string","nullable":true},"nfsePercentage":{"type":"string","nullable":true},"nfeConfig":{"type":"object","properties":{"barCode":{"type":"string","nullable":true},"fiscalDescription":{"type":"string","nullable":true},"commercialUnit":{"type":"string"},"taxUnit":{"type":"string"},"taxUnitExport":{"type":"string"},"internalCfop":{"type":"string","nullable":true},"interstateContributor":{"type":"string","nullable":true},"interstateNonContributor":{"type":"string","nullable":true},"internationalCfop":{"type":"string","nullable":true},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true,"description":"7 dígitos, sem pontos"},"taxRuleId":{"type":"string","nullable":true},"additionalInfo":{"type":"string","nullable":true},"icmsCst":{"type":"string","nullable":true,"description":"CST/CSOSN do ICMS"},"icmsRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS (%) (decimal como string)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%) (decimal como string)"},"icmsStModBc":{"type":"string","nullable":true,"description":"4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%) (decimal como string)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%) (decimal como string)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%) (decimal como string)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Crédito do Simples (%) (decimal como string)"},"icmsDesonValue":{"type":"string","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson, R$) (decimal como string)"},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS)"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson — abate o total da nota"},"icmsDeferralRate":{"type":"string","nullable":true,"description":"Percentual de diferimento (pDif, %) — CST 51 (decimal como string)"},"icmsCBenef":{"type":"string","nullable":true,"description":"Código de benefício fiscal da UF (<cBenef>)"},"icmsStRetBase":{"type":"string","nullable":true,"description":"Base de cálculo do ST retido anteriormente (vBCSTRet, R$) (decimal como string)"},"icmsStRetRate":{"type":"string","nullable":true,"description":"Alíquota suportada pelo consumidor final (pST, %) (decimal como string)"},"icmsSubstitutoValue":{"type":"string","nullable":true,"description":"ICMS próprio do substituto na operação anterior (vICMSSubstituto, R$) — opcional (decimal como string)"},"icmsStRetValue":{"type":"string","nullable":true,"description":"Valor do ICMS ST retido anteriormente (vICMSSTRet, R$) (decimal como string)"},"fcpStRetBase":{"type":"string","nullable":true,"description":"Base do FCP retido por ST (vBCFCPSTRet, R$) (decimal como string)"},"fcpStRetRate":{"type":"string","nullable":true,"description":"Alíquota do FCP retido por ST (pFCPSTRet, %) (decimal como string)"},"fcpStRetValue":{"type":"string","nullable":true,"description":"Valor do FCP retido por ST (vFCPSTRet, R$) (decimal como string)"},"pisCst":{"type":"string","nullable":true},"pisRate":{"type":"string","nullable":true,"description":"Alíquota do PIS (%) (decimal como string)"},"cofinsCst":{"type":"string","nullable":true},"cofinsRate":{"type":"string","nullable":true,"description":"Alíquota da COFINS (%) (decimal como string)"},"ipiCst":{"type":"string","nullable":true},"ipiRate":{"type":"string","nullable":true,"description":"Alíquota do IPI (%) (decimal como string)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (6 dígitos)"},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos)"}},"required":["barCode","fiscalDescription","commercialUnit","taxUnit","taxUnitExport","internalCfop","interstateContributor","interstateNonContributor","internationalCfop","ncm","cest","taxRuleId","additionalInfo","icmsCst","icmsRate","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","icmsCBenef","icmsStRetBase","icmsStRetRate","icmsSubstitutoValue","icmsStRetValue","fcpStRetBase","fcpStRetRate","fcpStRetValue","pisCst","pisRate","cofinsCst","cofinsRate","ipiCst","ipiRate","rtcCClassTrib","rtcCst"],"additionalProperties":false,"nullable":true},"nfseConfig":{"type":"object","properties":{"serviceDescription":{"type":"string"},"serviceListItem":{"type":"string","nullable":true},"municipalServiceCode":{"type":"string","nullable":true},"nbs":{"type":"string","nullable":true},"cnae":{"type":"string","nullable":true},"taxRuleId":{"type":"string","nullable":true},"useSpecificTaxation":{"type":"boolean"},"useIbpt":{"type":"boolean"},"issRate":{"type":"string","nullable":true,"description":"Alíquota do ISS (%) (decimal como string)"},"federalTax":{"type":"string"},"stateTax":{"type":"string"},"municipalTax":{"type":"string"}},"required":["serviceDescription","serviceListItem","municipalServiceCode","nbs","cnae","taxRuleId","useSpecificTaxation","useIbpt","issRate","federalTax","stateTax","municipalTax"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","description":"ISO 8601"},"updatedAt":{"type":"string","description":"ISO 8601"}},"required":["id","code","name","profile","salePrice","emissionModel","warranty","nfePercentage","nfsePercentage","nfeConfig","nfseConfig","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"delete":{"summary":"Exclui um produto","tags":["Products"],"description":"As notas já emitidas não mudam: o item guarda o snapshot (código, descrição, NCM, CFOP e impostos) do momento da emissão.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do produto"}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/suspicious":{"get":{"summary":"Notas recebidas que a empresa pode não reconhecer","tags":["Received Documents"],"description":"NF-e recebidas nos últimos 60 dias, ainda sem decisão (sem manifestação ou só Ciência), de um fornecedor que NUNCA emitiu para a empresa e que também fogem do padrão: valor acima de 5× a mediana das notas recebidas nos 12 meses anteriores (piso de R$ 1.000) ou mercadoria de capítulo de NCM fora do ramo. Pode ser nota fria contra o CNPJ — se a compra não aconteceu, manifeste Desconhecimento da operação (`210220`). Empresa com menos de 10 notas de histórico não tem suspeitas. É convite a conferir, nunca acusação. Exige o escopo `received-documents:read` literal (chave sem escopos não entra).","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accessKey":{"type":"string","nullable":true},"issuerCnpj":{"type":"string","nullable":true},"issuerName":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true},"emitDate":{"type":"string","nullable":true},"manifestation":{"type":"string"},"reasons":{"type":"array","items":{"type":"string","enum":["fornecedor_novo","valor_atipico","ramo_diferente"]}}},"required":["id","accessKey","issuerCnpj","issuerName","documentNumber","totalValue","emitDate","manifestation","reasons"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents":{"get":{"summary":"Lista as notas recebidas (DF-e) da empresa","tags":["Received Documents"],"description":"Notas emitidas CONTRA o CNPJ da empresa (fornecedores), baixadas pela Distribuição DF-e (NF-e) e pelo ADN (NFS-e do Padrão Nacional). Ordenadas por NSU decrescente. Use `pending=true` para a fila de manifestação: NF-e com chave e ainda sem manifestação. **Sincronização:** com `changedSince` (ou `cursor`) a lista vira a das notas CRIADAS OU ALTERADAS desde aquele instante — chegada do XML completo, manifestação, cancelamento —, em ordem de alteração, e `page` é ignorado: siga `meta.nextCursor` enquanto `meta.hasMore` for verdadeiro e GUARDE o último `nextCursor` — ele é o marco da próxima rodada (página vazia devolve o mesmo cursor recebido). Exige o escopo `received-documents:read` literal (chave sem escopos não entra).","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},{"schema":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"]},"in":"query","name":"schemaType","required":false},{"schema":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"in":"query","name":"manifestation","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"pending","required":false,"description":"true = só o que precisa de manifestação (ignora model/schemaType/manifestation)"},{"schema":{"type":"string"},"in":"query","name":"accessKey","required":false,"description":"Chave de acesso exata (44 dígitos)"},{"schema":{"type":"string"},"in":"query","name":"issuerCnpj","required":false,"description":"CNPJ do emitente (só dígitos ou formatado)"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Trecho da chave, do CNPJ ou do nome do emitente"},{"schema":{"type":"string","format":"date"},"in":"query","name":"emittedFrom","required":false,"description":"Emitidas a partir de (YYYY-MM-DD, BRT)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"emittedTo","required":false,"description":"Emitidas até (YYYY-MM-DD, BRT, inclusive)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"changedSince","required":false,"description":"Sincronização: notas criadas ou alteradas a partir deste instante (ISO 8601). Ignora `page`"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false,"description":"Sincronização: o `meta.nextCursor` da página anterior. Tem precedência sobre `changedSince`"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"nsu":{"type":"string","description":"NSU da distribuição. NF-e e NFS-e têm sequências INDEPENDENTES — o mesmo NSU pode aparecer nos dois modelos."},"model":{"type":"string","enum":["NFE","NFSE"],"description":"NFE (Distribuição DF-e) | NFSE (ADN nacional)"},"schemaType":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"],"description":"RES_NFE = só o RESUMO (manifeste Ciência para liberar o XML completo) · PROC_NFE = NF-e completa · RES_EVENTO/PROC_EVENTO = evento de uma NF-e · NFSE / EVENTO_NFSE = NFS-e do Padrão Nacional e seus eventos"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"issuerCnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente (o fornecedor)"},"issuerName":{"type":"string","nullable":true},"issuerStateReg":{"type":"string","nullable":true},"recipientCnpj":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"documentSeries":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"emitDate":{"type":"string","nullable":true,"description":"Emissão (ISO 8601)"},"situationCode":{"type":"string","nullable":true,"description":"cSitNFe: 1 = autorizada, 2 = cancelada, 3 = denegada"},"protocolNumber":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true,"description":"tpEvento, quando o documento é um evento"},"eventDescription":{"type":"string","nullable":true},"hasFullXml":{"type":"boolean","description":"true = o XML completo está disponível (e a DANFE pode ser gerada)"},"manifestation":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"manifestationDate":{"type":"string","nullable":true},"manifestationProtocol":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"Quando a nota chegou à Conttrole"},"updatedAt":{"type":"string"}},"required":["id","nsu","model","schemaType","accessKey","issuerCnpj","issuerName","issuerStateReg","recipientCnpj","documentNumber","documentSeries","totalValue","emitDate","situationCode","protocolNumber","eventType","eventDescription","hasFullXml","manifestation","manifestationDate","manifestationProtocol","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Só na sincronização: posição depois da última nota entregue. Guarde-o mesmo no fim — é o marco da próxima rodada"},"hasMore":{"type":"boolean","description":"Só na sincronização: há mais notas depois desta página"}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false}},"required":["data","meta"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/distribution":{"get":{"summary":"Estado da distribuição DF-e da empresa","tags":["Received Documents"],"description":"Cursor de NSU, último cStat e quando o próximo `POST /sync` é permitido. A distribuição roda sozinha a cada hora; use isto para saber se ela está andando antes de disparar uma manual.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false = a distribuição automática foi desligada para a empresa"},"hasCertificate":{"type":"boolean","description":"Sem certificado A1 a distribuição não roda (mTLS com a SEFAZ)"},"nfe":{"type":"object","properties":{"lastNsu":{"type":"string"},"maxNsu":{"type":"string"},"lastRunAt":{"type":"string","nullable":true},"lastStatus":{"type":"string","nullable":true,"description":"cStat da última consulta (137/138/656…)"},"lastMotive":{"type":"string","nullable":true},"nextSyncAllowedAt":{"type":"string","nullable":true,"description":"Antes disto o `POST /received-documents/sync` responde 429: a SEFAZ exige 1h de espera depois de 137/656. `null` = pode sincronizar."}},"required":["lastNsu","maxNsu","lastRunAt","lastStatus","lastMotive","nextSyncAllowedAt"],"additionalProperties":false},"nfse":{"type":"object","properties":{"lastNsu":{"type":"string"},"maxNsu":{"type":"string"},"lastRunAt":{"type":"string","nullable":true},"lastStatus":{"type":"string","nullable":true},"lastMotive":{"type":"string","nullable":true}},"required":["lastNsu","maxNsu","lastRunAt","lastStatus","lastMotive"],"additionalProperties":false}},"required":["enabled","hasCertificate","nfe","nfse"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/export":{"get":{"summary":"Baixa as notas recebidas do mês num ZIP (lote)","tags":["Received Documents"],"description":"Todas as notas recebidas de uma competência (mês de EMISSÃO, em BRT) num ZIP só: `notas/`, `eventos/` e, se pedidos, `resumos/`. Cada arquivo é `<chave>-nsu<NSU>.xml`. O ZIP é montado enquanto é baixado (não há limite de notas), e os headers `X-Document-Count` e `X-Pending-Summaries` chegam antes do corpo. `X-Pending-Summaries` > 0 significa NF-e das quais só existe o resumo: manifeste a Ciência (`POST .../{id}/manifestation`) e sincronize para receber o XML completo. Mês sem nada responde 404 `no_documents`. Resposta: `application/zip`. Exige o escopo `received-documents:read` literal (chave sem escopos não entra).","parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"year","required":false},{"schema":{"type":"integer","minimum":1,"maximum":12},"in":"query","name":"month","required":false,"description":"1–12"},{"schema":{"type":"boolean"},"in":"query","name":"notes","required":false,"description":"NF-e completas (`nfeProc`) e NFS-e. Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"events","required":false,"description":"Eventos (cancelamento, CC-e, manifestações, eventos de NFS-e). Default `true`."},{"schema":{"type":"boolean"},"in":"query","name":"summaries","required":false,"description":"RESUMOS (`resNFe`) das NF-e ainda não manifestadas — só dados básicos, sem a nota. Default `false`: para escrituração eles não servem, e o header `X-Pending-Summaries` diz quantos ficaram de fora."}],"security":[{"apiKey":[]}],"responses":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/export/link":{"post":{"summary":"Gera um link de download do ZIP do mês (sem header de autenticação)","tags":["Received Documents"],"description":"Em vez do ZIP, devolve um LINK que baixa o ZIP sem header de autenticação — para abrir no navegador ou entregar a uma pessoa (é o que o MCP usa). Vale por 15 minutos. 🔴 A credencial que pediu o link é conferida de novo no download: chave revogada, acesso desligado ou empresa que saiu da carteira derrubam o link na hora (`403 link_revoked`). Os números (`documentCount`, `pendingSummaries`) são os do ZIP. Mês sem nada responde 404 `no_documents`. Exige o escopo `received-documents:read` literal (chave sem escopos não entra).","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100,"nullable":true},"month":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"1–12"},"notes":{"type":"boolean","nullable":true,"description":"NF-e completas e NFS-e. Default `true`."},"events":{"type":"boolean","nullable":true,"description":"Eventos das notas. Default `true`."},"summaries":{"type":"boolean","nullable":true,"description":"Resumos das NF-e ainda não manifestadas. Default `false`."}},"additionalProperties":false,"nullable":true}]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Abre direto no navegador e baixa o ZIP — sem header de autenticação. Vale por 15 minutos e pode ser usado mais de uma vez nesse prazo."},"fileName":{"type":"string"},"expiresAt":{"type":"string","description":"ISO 8601"},"documentCount":{"type":"integer","description":"Documentos que vão no ZIP"},"companyCount":{"type":"integer","description":"Empresas com ao menos um documento"},"pendingSummaries":{"type":"integer","description":"NF-e das quais só existe o resumo — manifeste a Ciência para receber a nota"}},"required":["url","fileName","expiresAt","documentCount","companyCount","pendingSummaries"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/sync":{"post":{"summary":"Dispara a distribuição DF-e agora","tags":["Received Documents"],"description":"Busca na SEFAZ (NF-e) e no ADN (NFS-e) os documentos novos emitidos contra a empresa. Assíncrono: responde 202 e as notas aparecem em `GET /received-documents` em instantes. A distribuição já roda a cada hora — isto é para quando não dá para esperar. Depois de uma consulta sem novidades (cStat 137) a SEFAZ exige 1h de espera; dentro dela a resposta é 429 com `Retry-After`, porque insistir faria a SEFAZ bloquear a empresa (cStat 656). Se já houver uma sincronização em andamento, a resposta é 202 com `runId: null` — o pedido é atendido por ela.","security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"runId":{"type":"string","nullable":true},"message":{"type":"string"}},"required":["accepted","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/{id}":{"get":{"summary":"Detalha uma nota recebida","tags":["Received Documents"],"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"},"nsu":{"type":"string","description":"NSU da distribuição. NF-e e NFS-e têm sequências INDEPENDENTES — o mesmo NSU pode aparecer nos dois modelos."},"model":{"type":"string","enum":["NFE","NFSE"],"description":"NFE (Distribuição DF-e) | NFSE (ADN nacional)"},"schemaType":{"type":"string","enum":["RES_NFE","PROC_NFE","RES_EVENTO","PROC_EVENTO","NFSE","EVENTO_NFSE","OUTROS"],"description":"RES_NFE = só o RESUMO (manifeste Ciência para liberar o XML completo) · PROC_NFE = NF-e completa · RES_EVENTO/PROC_EVENTO = evento de uma NF-e · NFSE / EVENTO_NFSE = NFS-e do Padrão Nacional e seus eventos"},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (44 dígitos)"},"issuerCnpj":{"type":"string","nullable":true,"description":"CNPJ do emitente (o fornecedor)"},"issuerName":{"type":"string","nullable":true},"issuerStateReg":{"type":"string","nullable":true},"recipientCnpj":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"documentSeries":{"type":"string","nullable":true},"totalValue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"emitDate":{"type":"string","nullable":true,"description":"Emissão (ISO 8601)"},"situationCode":{"type":"string","nullable":true,"description":"cSitNFe: 1 = autorizada, 2 = cancelada, 3 = denegada"},"protocolNumber":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true,"description":"tpEvento, quando o documento é um evento"},"eventDescription":{"type":"string","nullable":true},"hasFullXml":{"type":"boolean","description":"true = o XML completo está disponível (e a DANFE pode ser gerada)"},"manifestation":{"type":"string","enum":["NONE","CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"manifestationDate":{"type":"string","nullable":true},"manifestationProtocol":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"Quando a nota chegou à Conttrole"},"updatedAt":{"type":"string"},"pdf":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":"string","nullable":true,"description":"Por que o PDF não pode ser gerado — e o que fazer"}},"required":["available","reason"],"additionalProperties":false,"description":"Se `GET /received-documents/{id}/danfe` vai funcionar. Resumo não tem DANFE; evento também não."}},"required":["id","nsu","model","schemaType","accessKey","issuerCnpj","issuerName","issuerStateReg","recipientCnpj","documentNumber","documentSeries","totalValue","emitDate","situationCode","protocolNumber","eventType","eventDescription","hasFullXml","manifestation","manifestationDate","manifestationProtocol","createdAt","updatedAt","pdf"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/{id}/xml":{"get":{"summary":"Baixa o XML da nota recebida","tags":["Received Documents"],"description":"O XML que chegou pela distribuição: o RESUMO (`resNFe`) enquanto a NF-e não foi manifestada, a nota completa (`nfeProc`) depois da Ciência, ou o evento. Confira `schemaType`/`hasFullXml` para saber qual é. Resposta: `application/xml`.","parameters":[{"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}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/{id}/danfe":{"get":{"summary":"Gera a DANFE/DANFSe (PDF) da nota recebida","tags":["Received Documents"],"description":"Só existe com o XML COMPLETO (`hasFullXml`). Resumo de NF-e responde 409 dizendo para manifestar a Ciência; evento responde 409 porque não tem DANFE. 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}],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}},"409":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/{id}/manifestation":{"post":{"summary":"Manifesta a nota recebida (MD-e)","tags":["Received Documents"],"description":"Envia à SEFAZ, EM NOME DA EMPRESA, a manifestação do destinatário. **É ato jurídico e não tem desfazer.** CIENCIA (210210) libera o XML completo; CONFIRMADA (210200) declara que a operação aconteceu; DESCONHECIDA (210220) e NAO_REALIZADA (210240) recusam a nota — e cancelam a conta a pagar gerada por ela (com baixa, vira pendência). NAO_REALIZADA exige `justification` de 15+ caracteres. Só NF-e: NFS-e não tem manifestação. Exige o escopo `received-documents:write` literal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{"type":{"type":"string","enum":["CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"],"nullable":true},"justification":{"type":"string","maxLength":255,"nullable":true}},"additionalProperties":false,"nullable":true}]}}}},"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]},"manifestation":{"type":"string","enum":["CIENCIA","CONFIRMADA","DESCONHECIDA","NAO_REALIZADA"]},"protocol":{"type":"string","nullable":true}},"required":["success","manifestation","protocol"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/received-documents/export/download":{"get":{"summary":"Baixa o ZIP de um link de download (sem header de autenticação)","tags":["Received Documents"],"description":"O destino da `url` devolvida por `POST .../received-documents/export/link` (chave da empresa ou do escritório). Não exige `Authorization`: o `token` é o pedido assinado, válido por 15 minutos, e a credencial que o gerou é conferida de novo aqui. Resposta: `application/zip`.","parameters":[{"schema":{"type":"string"},"in":"query","name":"token","required":false}],"security":[],"responses":{"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/simples/estimate":{"get":{"summary":"Estimativa do DAS da competência","tags":["Simples Nacional"],"description":"Calculada pelas notas AUTORIZADAS em produção, pelo histórico informado e pela folha (fator R). Faltando dado, `status: incomplete` com as pendências — nunca um valor calculado com zeros. Exige o escopo `simples:read` (não coberto por chave sem escopos).","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"in":"query","name":"competence","required":false,"description":"Competência AAAA-MM. Padrão: o mês corrente (horário de Brasília)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"competence":{"type":"string"},"regime":{"type":"string","enum":["SIMPLES","SIMPLES_EXCESSO","MEI","REGIME_NORMAL"]},"status":{"type":"string","enum":["calculated","two_scenarios","incomplete","not_applicable"],"description":"`two_scenarios`: há receita de fator R sem a folha informada — `scenarios` traz o DAS no Anexo III e no V. `not_applicable`: MEI ou regime normal."},"das":{"type":"object","properties":{"min":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"max":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["min","max"],"additionalProperties":false,"nullable":true,"description":"Iguais em `calculated`; III × V em `two_scenarios`; null nos demais"},"rbt12":{"type":"object","properties":{"internal":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"export":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"prorated":{"type":"boolean"}},"required":["internal","export","prorated"],"additionalProperties":false,"nullable":true},"fatorR":{"type":"object","properties":{"r":{"type":"number"},"annex":{"type":"string","enum":["III","V"]}},"required":["r","annex"],"additionalProperties":false,"nullable":true},"warnings":{"type":"array","items":{"type":"string"},"description":"cpp_fora_do_das | sublimite_excedido | teto_excedido | rbt12_proporcionalizada"},"pendencies":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"meses_sem_receita | receita_negativa | servicos_sem_anexo | transporte_nao_suportado | outras_receitas_sem_anexo"},"market":{"type":"string"},"months":{"type":"array","items":{"type":"string"},"description":"Competências sem receita (AAAA-MM)"},"items":{"type":"integer"},"value":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["type"],"additionalProperties":false}},"calculation":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false,"nullable":true},"scenarios":{"type":"object","properties":{"III":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false},"V":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false}},"required":["III","V"],"additionalProperties":false,"nullable":true}},"required":["companyId","competence","regime","status","das","rbt12","fatorR","warnings","pendencies","calculation","scenarios"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/simples/estimate":{"get":{"summary":"Estimativa do DAS de uma empresa da carteira","tags":["Accounting"],"description":"O mesmo cálculo de `GET /v1/simples/estimate`, pela chave do ESCRITÓRIO com `simples:read`. A empresa precisa ter vínculo ativo.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"in":"query","name":"competence","required":false,"description":"Competência AAAA-MM. Padrão: o mês corrente (horário de Brasília)."},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"competence":{"type":"string"},"regime":{"type":"string","enum":["SIMPLES","SIMPLES_EXCESSO","MEI","REGIME_NORMAL"]},"status":{"type":"string","enum":["calculated","two_scenarios","incomplete","not_applicable"],"description":"`two_scenarios`: há receita de fator R sem a folha informada — `scenarios` traz o DAS no Anexo III e no V. `not_applicable`: MEI ou regime normal."},"das":{"type":"object","properties":{"min":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"max":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["min","max"],"additionalProperties":false,"nullable":true,"description":"Iguais em `calculated`; III × V em `two_scenarios`; null nos demais"},"rbt12":{"type":"object","properties":{"internal":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"export":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"prorated":{"type":"boolean"}},"required":["internal","export","prorated"],"additionalProperties":false,"nullable":true},"fatorR":{"type":"object","properties":{"r":{"type":"number"},"annex":{"type":"string","enum":["III","V"]}},"required":["r","annex"],"additionalProperties":false,"nullable":true},"warnings":{"type":"array","items":{"type":"string"},"description":"cpp_fora_do_das | sublimite_excedido | teto_excedido | rbt12_proporcionalizada"},"pendencies":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"meses_sem_receita | receita_negativa | servicos_sem_anexo | transporte_nao_suportado | outras_receitas_sem_anexo"},"market":{"type":"string"},"months":{"type":"array","items":{"type":"string"},"description":"Competências sem receita (AAAA-MM)"},"items":{"type":"integer"},"value":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["type"],"additionalProperties":false}},"calculation":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false,"nullable":true},"scenarios":{"type":"object","properties":{"III":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false},"V":{"type":"object","properties":{"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"lines":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string","description":"I | II | III | IV | V"},"market":{"type":"string","enum":["interno","exportacao"]},"revenue":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"bracket":{"type":"integer","description":"Faixa (1 a 6)"},"nominalRate":{"type":"number"},"deduction":{"type":"string","description":"Parcela a deduzir da faixa"},"effectiveRate":{"type":"number","description":"(RBT12 × nominal − parcela a deduzir) ÷ RBT12, em %"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax":{"type":"string","description":"IRPJ | CSLL | COFINS | PIS | CPP | ICMS | IPI | ISS"},"rate":{"type":"number","description":"Percentual efetivo do tributo sobre a receita"},"amount":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"excludedReason":{"type":"string","nullable":true,"description":"Fora do DAS: icms_st | monofasico | iss_retido | locacao_bem_movel | exportacao"}},"required":["tax","rate","amount","excludedReason"],"additionalProperties":false}}},"required":["annex","market","revenue","rbt12","bracket","nominalRate","deduction","effectiveRate","amount","taxes"],"additionalProperties":false}}},"required":["amount","lines"],"additionalProperties":false}},"required":["III","V"],"additionalProperties":false,"nullable":true}},"required":["companyId","competence","regime","status","das","rbt12","fatorR","warnings","pendencies","calculation","scenarios"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/simples/estimates":{"get":{"summary":"DAS estimado de toda a carteira","tags":["Accounting"],"description":"Uma linha por empresa com vínculo ativo (até 200). Empresa cuja conta falhar volta com `status: error` — as outras não são afetadas.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"in":"query","name":"competence","required":false,"description":"Competência AAAA-MM. Padrão: o mês corrente (horário de Brasília)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"companyId":{"type":"string"},"competence":{"type":"string"},"regime":{"type":"string"},"status":{"type":"string","enum":["calculated","two_scenarios","incomplete","not_applicable","error"]},"das":{"type":"object","properties":{"min":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"max":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["min","max"],"additionalProperties":false,"nullable":true},"pendencies":{"type":"integer","description":"Quantas pendências impedem o número"}},"required":["companyId","competence","regime","status","das","pendencies"],"additionalProperties":false}}},"required":["data"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/simples/regime-ibscbs":{"get":{"summary":"IBS/CBS por dentro × por fora do DAS (simulação)","tags":["Simples Nacional"],"description":"A partir de 2027 o optante do Simples pode recolher IBS e CBS fora do DAS, pelo regime regular (LC 123, art. 13, §§ 10–11; opção em setembro para jan–jun e em março para jul–dez). Compara, com as notas dos últimos 12 meses, o imposto da empresa e o crédito que os clientes com CNPJ recuperam nos dois regimes. É ESTIMATIVA com premissas (`premises`), nunca recomendação fiscal. Enquanto a CBS do ano não for publicada, a resposta é `status: cbs_not_published` — mande `cbs` (% a simular) para obter o número, que volta marcado como premissa. Cobre 2027 e 2028. Escopo `simples:read`.","parameters":[{"schema":{"type":"integer"},"in":"query","name":"year","required":false,"description":"2027 ou 2028. Padrão: o ano seguinte."},{"schema":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":30},"in":"query","name":"cbs","required":false,"description":"CBS a simular (%), quando não publicada"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"status":{"type":"string","enum":["calculated","out_of_range","no_revenue","cbs_not_published","estimate_unavailable","not_applicable"],"description":"`cbs_not_published`: mande `cbs`. `estimate_unavailable`: a estimativa do DAS não fecha (veja GET /v1/simples/estimate). `out_of_range`: só 2027–2028. `not_applicable`: MEI ou regime normal."},"year":{"type":"integer","nullable":true},"baseCompetence":{"type":"string","nullable":true},"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false,"nullable":true},"inside":{"type":"object","properties":{"das":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"clientsCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["das","clientsCredit"],"additionalProperties":false,"nullable":true,"description":"Ficando no DAS"},"outside":{"type":"object","properties":{"dasWithoutIbsCbs":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"ibsCbsDebit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"purchasesCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"total":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"clientsCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["dasWithoutIbsCbs","ibsCbsDebit","purchasesCredit","total","clientsCredit"],"additionalProperties":false,"nullable":true,"description":"IBS/CBS pelo regime regular"},"difference":{"type":"string","nullable":true,"description":"outside.total − inside.das. Positivo = sair custa mais à empresa"},"extraClientsCredit":{"type":"string","nullable":true,"description":"Crédito a mais que os clientes com CNPJ recuperariam saindo"},"reading":{"type":"string","enum":["outside_costs_less","outside_costs_more_clients_gain_more","outside_costs_more"],"nullable":true},"creditPer100":{"type":"object","properties":{"inside":{"type":"number"},"outside":{"type":"number"}},"required":["inside","outside"],"additionalProperties":false,"nullable":true},"cnpjRevenueShare":{"type":"number","nullable":true,"description":"0 a 1"},"rates":{"type":"object","properties":{"ibs":{"type":"number"},"cbs":{"type":"number"},"cbsOrigin":{"type":"string","enum":["norma","premissa"]},"source":{"type":"string"}},"required":["ibs","cbs","cbsOrigin","source"],"additionalProperties":false,"nullable":true},"revenue":{"type":"object","properties":{"cnpj":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"others":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["cnpj","others"],"additionalProperties":false,"nullable":true},"purchases":{"type":"object","properties":{"regularRegime":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"simples":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"unclassified":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"count":{"type":"integer"}},"required":["regularRegime","simples","unclassified","count"],"additionalProperties":false,"nullable":true},"premises":{"type":"array","items":{"type":"string"}},"nextOptionWindow":{"type":"object","properties":{"month":{"type":"string","enum":["setembro","marco"]},"year":{"type":"integer"},"validFor":{"type":"string"}},"required":["month","year","validFor"],"additionalProperties":false,"nullable":true}},"required":["companyId","status","year","baseCompetence","period","inside","outside","difference","extraClientsCredit","reading","creditPer100","cnpjRevenueShare","rates","revenue","purchases","premises","nextOptionWindow"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/simples/regime-ibscbs":{"get":{"summary":"IBS/CBS por dentro × por fora do DAS — empresa da carteira","tags":["Accounting"],"description":"A partir de 2027 o optante do Simples pode recolher IBS e CBS fora do DAS, pelo regime regular (LC 123, art. 13, §§ 10–11; opção em setembro para jan–jun e em março para jul–dez). Compara, com as notas dos últimos 12 meses, o imposto da empresa e o crédito que os clientes com CNPJ recuperam nos dois regimes. É ESTIMATIVA com premissas (`premises`), nunca recomendação fiscal. Enquanto a CBS do ano não for publicada, a resposta é `status: cbs_not_published` — mande `cbs` (% a simular) para obter o número, que volta marcado como premissa. Cobre 2027 e 2028. Escopo `simples:read`.","parameters":[{"schema":{"type":"integer"},"in":"query","name":"year","required":false,"description":"2027 ou 2028. Padrão: o ano seguinte."},{"schema":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":30},"in":"query","name":"cbs","required":false,"description":"CBS a simular (%), quando não publicada"},{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"status":{"type":"string","enum":["calculated","out_of_range","no_revenue","cbs_not_published","estimate_unavailable","not_applicable"],"description":"`cbs_not_published`: mande `cbs`. `estimate_unavailable`: a estimativa do DAS não fecha (veja GET /v1/simples/estimate). `out_of_range`: só 2027–2028. `not_applicable`: MEI ou regime normal."},"year":{"type":"integer","nullable":true},"baseCompetence":{"type":"string","nullable":true},"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false,"nullable":true},"inside":{"type":"object","properties":{"das":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"clientsCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["das","clientsCredit"],"additionalProperties":false,"nullable":true,"description":"Ficando no DAS"},"outside":{"type":"object","properties":{"dasWithoutIbsCbs":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"ibsCbsDebit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"purchasesCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"total":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"clientsCredit":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["dasWithoutIbsCbs","ibsCbsDebit","purchasesCredit","total","clientsCredit"],"additionalProperties":false,"nullable":true,"description":"IBS/CBS pelo regime regular"},"difference":{"type":"string","nullable":true,"description":"outside.total − inside.das. Positivo = sair custa mais à empresa"},"extraClientsCredit":{"type":"string","nullable":true,"description":"Crédito a mais que os clientes com CNPJ recuperariam saindo"},"reading":{"type":"string","enum":["outside_costs_less","outside_costs_more_clients_gain_more","outside_costs_more"],"nullable":true},"creditPer100":{"type":"object","properties":{"inside":{"type":"number"},"outside":{"type":"number"}},"required":["inside","outside"],"additionalProperties":false,"nullable":true},"cnpjRevenueShare":{"type":"number","nullable":true,"description":"0 a 1"},"rates":{"type":"object","properties":{"ibs":{"type":"number"},"cbs":{"type":"number"},"cbsOrigin":{"type":"string","enum":["norma","premissa"]},"source":{"type":"string"}},"required":["ibs","cbs","cbsOrigin","source"],"additionalProperties":false,"nullable":true},"revenue":{"type":"object","properties":{"cnpj":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"others":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["cnpj","others"],"additionalProperties":false,"nullable":true},"purchases":{"type":"object","properties":{"regularRegime":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"simples":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"unclassified":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"count":{"type":"integer"}},"required":["regularRegime","simples","unclassified","count"],"additionalProperties":false,"nullable":true},"premises":{"type":"array","items":{"type":"string"}},"nextOptionWindow":{"type":"object","properties":{"month":{"type":"string","enum":["setembro","marco"]},"year":{"type":"integer"},"validFor":{"type":"string"}},"required":["month","year","validFor"],"additionalProperties":false,"nullable":true}},"required":["companyId","status","year","baseCompetence","period","inside","outside","difference","extraClientsCredit","reading","creditPer100","cnpjRevenueShare","rates","revenue","purchases","premises","nextOptionWindow"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/simples/forecast":{"get":{"summary":"Previsão do DAS do mês corrente","tags":["Simples Nacional"],"description":"Quanto o DAS do mês corrente deve fechar se o mês seguir no ritmo dos dias já decorridos (horário de Brasília), e a RBT12 e a faixa do MÊS SEGUINTE — com aviso antecipado de troca de faixa, sublimite (R$ 3,6 mi) e teto (R$ 4,8 mi). `fewDays: true` = menos de 7 dias, projeção instável. Escopo `simples:read`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"status":{"type":"string","enum":["forecast","no_revenue","estimate_unavailable","not_applicable"]},"competence":{"type":"string","nullable":true},"daysElapsed":{"type":"integer","nullable":true},"daysInMonth":{"type":"integer","nullable":true},"fewDays":{"type":"boolean","nullable":true},"revenueSoFar":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"projectedRevenue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"dasSoFar":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"projectedDas":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"nextMonth":{"type":"object","properties":{"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"brackets":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string"},"currentBracket":{"type":"integer"},"newBracket":{"type":"integer"},"currentEffectiveRate":{"type":"number"},"newEffectiveRate":{"type":"number"}},"required":["annex","currentBracket","newBracket","currentEffectiveRate","newEffectiveRate"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string","enum":["muda_de_faixa","sublimite","teto"]}}},"required":["rbt12","brackets","warnings"],"additionalProperties":false,"nullable":true,"description":"null quando a RBT12 é proporcionalizada (início de atividade) ou falta o mês que sai da base"}},"required":["companyId","status","competence","daysElapsed","daysInMonth","fewDays","revenueSoFar","projectedRevenue","dasSoFar","projectedDas","nextMonth"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/accounting/companies/{companyId}/simples/forecast":{"get":{"summary":"Previsão do DAS do mês — empresa da carteira","tags":["Accounting"],"description":"Quanto o DAS do mês corrente deve fechar se o mês seguir no ritmo dos dias já decorridos (horário de Brasília), e a RBT12 e a faixa do MÊS SEGUINTE — com aviso antecipado de troca de faixa, sublimite (R$ 3,6 mi) e teto (R$ 4,8 mi). `fewDays: true` = menos de 7 dias, projeção instável. Escopo `simples:read`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"companyId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"status":{"type":"string","enum":["forecast","no_revenue","estimate_unavailable","not_applicable"]},"competence":{"type":"string","nullable":true},"daysElapsed":{"type":"integer","nullable":true},"daysInMonth":{"type":"integer","nullable":true},"fewDays":{"type":"boolean","nullable":true},"revenueSoFar":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"projectedRevenue":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"dasSoFar":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"projectedDas":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"nextMonth":{"type":"object","properties":{"rbt12":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"brackets":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string"},"currentBracket":{"type":"integer"},"newBracket":{"type":"integer"},"currentEffectiveRate":{"type":"number"},"newEffectiveRate":{"type":"number"}},"required":["annex","currentBracket","newBracket","currentEffectiveRate","newEffectiveRate"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string","enum":["muda_de_faixa","sublimite","teto"]}}},"required":["rbt12","brackets","warnings"],"additionalProperties":false,"nullable":true,"description":"null quando a RBT12 é proporcionalizada (início de atividade) ou falta o mês que sai da base"}},"required":["companyId","status","competence","daysElapsed","daysInMonth","fewDays","revenueSoFar","projectedRevenue","dasSoFar","projectedDas","nextMonth"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/simples/pricing":{"get":{"summary":"Quanto do preço de um produto é imposto (Simples)","tags":["Simples Nacional"],"description":"Alíquota efetiva do DAS para o produto (anexo pelo CFOP de venda ou pelo anexo do serviço), quanto do preço vai para o DAS, a margem do preço e o PREÇO MÍNIMO para a margem desejada: custo ÷ (1 − imposto − despesas − margem). `minimumPrice: null` = a soma passa de 100% e nenhum preço fecha. Fator R sem folha devolve os cenários III e V. Só Simples; nada é gravado. Escopo `simples:read`.","parameters":[{"schema":{"type":"string"},"in":"query","name":"productId","required":true},{"schema":{"type":"string"},"in":"query","name":"cost","required":true,"description":"Custo unitário"},{"schema":{"type":"string"},"in":"query","name":"price","required":false,"description":"Preço a avaliar. Padrão: o preço de venda cadastrado"},{"schema":{"type":"number","minimum":0,"maximum":99.99},"in":"query","name":"expensesRate","required":false,"description":"Outras despesas, % do preço"},{"schema":{"type":"number","minimum":0,"maximum":99.99},"in":"query","name":"marginRate","required":false,"description":"Margem desejada, % do preço"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["calculated","no_annex","estimate_unavailable","not_applicable"]},"reason":{"type":"string","nullable":true,"description":"Em `no_annex`: servico_sem_anexo | cfop_sem_classificacao"},"product":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"price":{"type":"string","description":"Valor decimal em string (\"1234.56\")"}},"required":["id","code","name","price"],"additionalProperties":false,"nullable":true},"rbt12":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"},"icmsSt":{"type":"boolean","nullable":true,"description":"CSOSN 500: a alíquota já vem sem o ICMS"},"scenarios":{"type":"array","items":{"type":"object","properties":{"annex":{"type":"string"},"effectiveRate":{"type":"number"},"taxInPrice":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"expensesInPrice":{"type":"string","description":"Valor decimal em string (\"1234.56\")"},"profit":{"type":"string","description":"Pode ser negativo"},"marginRate":{"type":"number","nullable":true},"minimumPrice":{"type":"string","nullable":true,"description":"Valor decimal em string (\"1234.56\")"}},"required":["annex","effectiveRate","taxInPrice","expensesInPrice","profit","marginRate","minimumPrice"],"additionalProperties":false}}},"required":["status","reason","product","rbt12","icmsSt","scenarios"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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"}},"cfops":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"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)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%)"},"icmsStModBc":{"type":"string","nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Alíquota de crédito do Simples (%)"},"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},"rtcCClassTrib":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"icmsDesonValue":{"type":"string","nullable":true},"icmsDesonReason":{"type":"string","nullable":true},"icmsDesonDeduct":{"type":"boolean","nullable":true},"icmsDeferralRate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","cfops","operationNature","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","rtcCClassTrib","rtcCst","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","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"},"issExigibility":{"type":"string","nullable":true},"issSuspensionProcess":{"type":"string","nullable":true},"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","issExigibility","issSuspensionProcess","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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. Sub-regra NF-e que a emissão recusaria volta 422 `invalid_taxation` com o motivo: CST da tabela do Regime Normal numa empresa do Simples (ou CSOSN fora dele), ICMS-ST (CST 10/30/70, CSOSN 201/202/203) sem modalidade, MVA ou alíquota do ST, CSOSN 101/201 sem a alíquota de crédito, CST 20/70 sem a redução da base. Parâmetro que o código não usa é gravado nulo.","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"},"cfops":{"type":"array","items":{"type":"string"},"description":"CFOPs da operação em que a sub-regra vale (vazio = qualquer). Casa pelos 3 últimos dígitos: 5910 vale também para 6910. Sub-regra com CFOP vence as sem CFOP da mesma regra (bonificação, remessa, demonstração…)."},"operationNature":{"type":"string","maxLength":60,"nullable":true,"description":"Natureza da operação (<natOp>) que a sub-regra declara — ex.: 'Bonificação' numa sub-regra de CFOP 5910. Vale quando a nota não informa a sua; vazio = padrão do tipo ('Venda de mercadoria')."},"icmsCst":{"type":"string","description":"CST (Regime Normal) ou CSOSN (Simples Nacional/MEI) do ICMS. Precisa ser da tabela do regime da empresa — senão 422 `invalid_taxation`."},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%)"},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — exigida nos CST 20 e 70"},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação. Exigida nos CST 10/30/70 e CSOSN 201/202/203."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%) — exigida na modalidade 4"},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%) — opcional"},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota interna do ICMS-ST no destino (%) — exigida nos CST 10/30/70 e CSOSN 201/202/203"},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — exigida nos CSOSN 101 e 201"},"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 (%)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). O CST são os 3 primeiros dígitos dela. 🔴 Não é conferido contra a tabela oficial — ela é publicada fora do XSD, que valida só o formato, então um código errado é ACEITO e a nota sai declarando outra classificação."},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Omita: é derivado do cClassTrib. Informado e divergente, o par inteiro é recusado com 400."},"ipiCEnq":{"type":"string","nullable":true,"description":"Código de enquadramento do IPI"},"icmsDesonValue":{"type":"number","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson). O motivo é enumerado POR CST."},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS) — precisa ser um dos aceitos pelo CST"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson: true ABATE o desonerado do valor da nota"},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual do diferimento (pDif, CST 51)"},"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"},"issExigibility":{"type":"string","nullable":true,"description":"Exigibilidade do ISS (tabela ABRASF 1–7). 6 e 7 exigem o processo de suspensão."},"issSuspensionProcess":{"type":"string","nullable":true,"description":"Número do processo de suspensão da exigibilidade (exigibilidade 6 ou 7)"},"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"}},"cfops":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"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)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%)"},"icmsStModBc":{"type":"string","nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Alíquota de crédito do Simples (%)"},"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},"rtcCClassTrib":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"icmsDesonValue":{"type":"string","nullable":true},"icmsDesonReason":{"type":"string","nullable":true},"icmsDesonDeduct":{"type":"boolean","nullable":true},"icmsDeferralRate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","cfops","operationNature","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","rtcCClassTrib","rtcCst","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","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"},"issExigibility":{"type":"string","nullable":true},"issSuspensionProcess":{"type":"string","nullable":true},"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","issExigibility","issSuspensionProcess","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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"}},"cfops":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"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)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%)"},"icmsStModBc":{"type":"string","nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Alíquota de crédito do Simples (%)"},"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},"rtcCClassTrib":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"icmsDesonValue":{"type":"string","nullable":true},"icmsDesonReason":{"type":"string","nullable":true},"icmsDesonDeduct":{"type":"boolean","nullable":true},"icmsDeferralRate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","cfops","operationNature","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","rtcCClassTrib","rtcCst","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","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"},"issExigibility":{"type":"string","nullable":true},"issSuspensionProcess":{"type":"string","nullable":true},"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","issExigibility","issSuspensionProcess","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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. As sub-regras NF-e enviadas passam pela mesma validação da criação (422 `invalid_taxation`).","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"},"cfops":{"type":"array","items":{"type":"string"},"description":"CFOPs da operação em que a sub-regra vale (vazio = qualquer). Casa pelos 3 últimos dígitos: 5910 vale também para 6910. Sub-regra com CFOP vence as sem CFOP da mesma regra (bonificação, remessa, demonstração…)."},"operationNature":{"type":"string","maxLength":60,"nullable":true,"description":"Natureza da operação (<natOp>) que a sub-regra declara — ex.: 'Bonificação' numa sub-regra de CFOP 5910. Vale quando a nota não informa a sua; vazio = padrão do tipo ('Venda de mercadoria')."},"icmsCst":{"type":"string","description":"CST (Regime Normal) ou CSOSN (Simples Nacional/MEI) do ICMS. Precisa ser da tabela do regime da empresa — senão 422 `invalid_taxation`."},"icmsModBc":{"type":"string","nullable":true},"icmsCBenFiscal":{"type":"string","nullable":true},"icmsPIcms":{"type":"number","nullable":true,"description":"Alíquota de ICMS (%)"},"icmsRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS (%) — exigida nos CST 20 e 70"},"icmsStModBc":{"type":"string","enum":["4","6"],"nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação. Exigida nos CST 10/30/70 e CSOSN 201/202/203."},"icmsStMva":{"type":"number","nullable":true,"description":"MVA do ICMS-ST (%) — exigida na modalidade 4"},"icmsStRedBc":{"type":"number","nullable":true,"description":"Redução da base do ICMS-ST (%) — opcional"},"icmsStRate":{"type":"number","nullable":true,"description":"Alíquota interna do ICMS-ST no destino (%) — exigida nos CST 10/30/70 e CSOSN 201/202/203"},"icmsSnCreditRate":{"type":"number","nullable":true,"description":"Alíquota de crédito do Simples (pCredSN, %) — exigida nos CSOSN 101 e 201"},"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 (%)"},"rtcCClassTrib":{"type":"string","nullable":true,"description":"Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). O CST são os 3 primeiros dígitos dela. 🔴 Não é conferido contra a tabela oficial — ela é publicada fora do XSD, que valida só o formato, então um código errado é ACEITO e a nota sai declarando outra classificação."},"rtcCst":{"type":"string","nullable":true,"description":"CST do IBS/CBS (3 dígitos). Omita: é derivado do cClassTrib. Informado e divergente, o par inteiro é recusado com 400."},"ipiCEnq":{"type":"string","nullable":true,"description":"Código de enquadramento do IPI"},"icmsDesonValue":{"type":"number","nullable":true,"description":"Valor do ICMS desonerado (vICMSDeson). O motivo é enumerado POR CST."},"icmsDesonReason":{"type":"string","nullable":true,"description":"Motivo da desoneração (motDesICMS) — precisa ser um dos aceitos pelo CST"},"icmsDesonDeduct":{"type":"boolean","nullable":true,"description":"indDeduzDeson: true ABATE o desonerado do valor da nota"},"icmsDeferralRate":{"type":"number","nullable":true,"description":"Percentual do diferimento (pDif, CST 51)"},"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"},"issExigibility":{"type":"string","nullable":true,"description":"Exigibilidade do ISS (tabela ABRASF 1–7). 6 e 7 exigem o processo de suspensão."},"issSuspensionProcess":{"type":"string","nullable":true,"description":"Número do processo de suspensão da exigibilidade (exigibilidade 6 ou 7)"},"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"}},"cfops":{"type":"array","items":{"type":"string"}},"operationNature":{"type":"string","nullable":true},"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)"},"icmsRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS (%)"},"icmsStModBc":{"type":"string","nullable":true,"description":"Modalidade da base do ICMS-ST: 4 = MVA, 6 = valor da operação"},"icmsStMva":{"type":"string","nullable":true,"description":"MVA do ICMS-ST (%)"},"icmsStRedBc":{"type":"string","nullable":true,"description":"Redução da base do ICMS-ST (%)"},"icmsStRate":{"type":"string","nullable":true,"description":"Alíquota do ICMS-ST (%)"},"icmsSnCreditRate":{"type":"string","nullable":true,"description":"Alíquota de crédito do Simples (%)"},"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},"rtcCClassTrib":{"type":"string","nullable":true},"rtcCst":{"type":"string","nullable":true},"icmsDesonValue":{"type":"string","nullable":true},"icmsDesonReason":{"type":"string","nullable":true},"icmsDesonDeduct":{"type":"boolean","nullable":true},"icmsDeferralRate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","states","clientTypes","cfops","operationNature","icmsCst","icmsModBc","icmsCBenFiscal","icmsPIcms","icmsRedBc","icmsStModBc","icmsStMva","icmsStRedBc","icmsStRate","icmsSnCreditRate","pisCst","pisPPis","cofinsCst","cofinsPCofins","ipiCst","ipiPIpi","ipiCEnq","rtcCClassTrib","rtcCst","icmsDesonValue","icmsDesonReason","icmsDesonDeduct","icmsDeferralRate","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"},"issExigibility":{"type":"string","nullable":true},"issSuspensionProcess":{"type":"string","nullable":true},"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","issExigibility","issSuspensionProcess","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Ambientes recebidos. Vazio = os dois. Use para mandar homologação só para o seu endpoint de testes."},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Tipos recebidos. Vazio = todos. Use para separar mercadoria (NF-e/NFC-e) de serviço (NFS-e)."},"isActive":{"type":"boolean"},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true,"description":"Motivo, quando o endpoint foi desativado automaticamente"},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","environments","documentTypes","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"post":{"summary":"Cria um endpoint de webhook","tags":["Webhooks"],"description":"Antes de cadastrar, a Conttrole faz um POST de verificação assinado ao endpoint: ele precisa responder **2xx** em até 10s, senão a criação é recusada com **422** (`webhook_unreachable`). Retorna o `secret` de assinatura UMA única vez. Use-o para validar o header `X-Webhook-Signature: t=<ts>,v1=<hmac>` (HMAC-SHA256 de `<ts>.<corpo>`). O legado `X-Conttrole-Signature` segue sendo enviado com o mesmo valor até 01/02/2027.","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},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Vazio/omitido = recebe os dois ambientes"},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Vazio/omitido = recebe todos os tipos"},"events":{"type":"array","items":{"type":"string","enum":["DOCUMENT_AUTHORIZED","DOCUMENT_REJECTED","DOCUMENT_CANCELLED","DOCUMENT_INUTILIZED","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Eventos assinados. Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Ambientes recebidos. Vazio = os dois. Use para mandar homologação só para o seu endpoint de testes."},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Tipos recebidos. Vazio = todos. Use para separar mercadoria (NF-e/NFC-e) de serviço (NFS-e)."},"isActive":{"type":"boolean"},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true,"description":"Motivo, quando o endpoint foi desativado automaticamente"},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura — exibido apenas uma vez. Guarde-o."}},"required":["id","url","description","events","environments","documentTypes","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Ambientes recebidos. Vazio = os dois. Use para mandar homologação só para o seu endpoint de testes."},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Tipos recebidos. Vazio = todos. Use para separar mercadoria (NF-e/NFC-e) de serviço (NFS-e)."},"isActive":{"type":"boolean"},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true,"description":"Motivo, quando o endpoint foi desativado automaticamente"},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","environments","documentTypes","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}},"patch":{"summary":"Atualiza um endpoint de webhook","tags":["Webhooks"],"description":"Reativar (`isActive: true`) ou trocar a `url` de um endpoint ativo dispara um POST de verificação: se o endpoint não responder 2xx, a operação é recusada com **422** (`webhook_unreachable`). Reativar também zera o contador de falhas.","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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"}},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Ambientes recebidos. Vazio = os dois. Use para mandar homologação só para o seu endpoint de testes."},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Tipos recebidos. Vazio = todos. Use para separar mercadoria (NF-e/NFC-e) de serviço (NFS-e)."},"isActive":{"type":"boolean"},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true,"description":"Motivo, quando o endpoint foi desativado automaticamente"},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","environments","documentTypes","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"description":"Vazio = todos os eventos de documento. Os eventos GNRE_ISSUED, GNRE_REJECTED NÃO entram no \"todos\": só são entregues a endpoint que os lista pelo nome."},"environments":{"type":"array","items":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Ambiente fiscal do documento"},"description":"Ambientes recebidos. Vazio = os dois. Use para mandar homologação só para o seu endpoint de testes."},"documentTypes":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"],"description":"Tipo do documento fiscal"},"description":"Tipos recebidos. Vazio = todos. Use para separar mercadoria (NF-e/NFC-e) de serviço (NFS-e)."},"isActive":{"type":"boolean"},"consecutiveFailures":{"type":"integer","description":"Entregas que falharam em sequência (zera a cada sucesso)"},"disabledReason":{"type":"string","nullable":true,"description":"Motivo, quando o endpoint foi desativado automaticamente"},"disabledAt":{"type":"string","nullable":true},"lastSuccessAt":{"type":"string","nullable":true},"lastFailureAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura — exibido apenas uma vez. Guarde-o."}},"required":["id","url","description","events","environments","documentTypes","isActive","consecutiveFailures","disabledReason","disabledAt","lastSuccessAt","lastFailureAt","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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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","GNRE_ISSUED","GNRE_REJECTED"],"description":"Evento assinado pelo endpoint. `GNRE_ISSUED`/`GNRE_REJECTED` (guia GNRE emitida/rejeitada) são EXPLICIT-ONLY: só chegam a quem os lista."},"eventId":{"type":"string"},"status":{"type":"string","description":"PENDING | SUCCEEDED | FAILED"},"attempts":{"type":"integer"},"payload":{"type":"object","properties":{"id":{"type":"string","description":"Id do evento (`evt_...`) — use para deduplicar"},"type":{"type":"string","description":"document.authorized | document.rejected | document.cancelled | document.inutilized | gnre.issued | gnre.rejected | webhook.test"},"createdAt":{"type":"string"},"data":{"type":"object","properties":{"documentId":{"type":"string","description":"ID da nota no Conttrole"},"externalId":{"type":"string","nullable":true,"description":"Id da venda no SEU sistema, informado na criação da nota"},"type":{"type":"string","description":"NFE | NFCE | NFSE"},"series":{"type":"integer","nullable":true},"number":{"type":"integer","nullable":true},"accessKey":{"type":"string","nullable":true,"description":"Chave de acesso (NF-e/NFC-e)"},"nfseNumber":{"type":"string","nullable":true,"description":"Número da NFS-e"},"authorizationDate":{"type":"string","nullable":true},"protocolNumber":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true,"description":"Presente em document.rejected e gnre.rejected"},"cancellationReason":{"type":"string","nullable":true,"description":"Presente em document.cancelled"},"totalValue":{"type":"string","description":"Valor total, como string"},"inutilizationId":{"type":"string"},"model":{"type":"string"},"startNumber":{"type":"integer"},"endNumber":{"type":"integer"},"year":{"type":"integer"},"protocol":{"type":"string","nullable":true},"justification":{"type":"string"},"guideId":{"type":"string","description":"ID da guia GNRE (gnre.*)"},"fiscalDocumentId":{"type":"string","description":"Nota que originou a guia (gnre.*)"},"ufFavorecida":{"type":"string","description":"UF que recebe o recolhimento (gnre.*)"},"receita":{"type":"string","description":"Código de receita do Portal GNRE, ex. 100102 (gnre.*)"},"kind":{"type":"string","description":"DIFAL | FCP | ST | FCP_ST (gnre.*)"},"status":{"type":"string","description":"ISSUED | REJECTED (gnre.*)"},"total":{"type":"string","description":"Valor da guia, decimal em string (\"123.45\") (gnre.*)"},"dueDate":{"type":"string","description":"Vencimento AAAA-MM-DD (gnre.*)"},"digitableLine":{"type":"string","nullable":true,"description":"Linha digitável (gnre.issued)"},"barcode":{"type":"string","nullable":true,"description":"Código de barras (gnre.issued)"},"pixCopiaECola":{"type":"string","nullable":true,"description":"Pix \"copia e cola\", quando a UF aceita Pix (gnre.issued)"},"environment":{"type":"string","description":"PRODUCTION | HOMOLOGATION"},"message":{"type":"string"}},"additionalProperties":true}},"additionalProperties":true,"description":"Corpo exato enviado ao endpoint — o mesmo JSON sobre o qual a assinatura HMAC foi calculada"},"responseStatus":{"type":"integer","nullable":true},"responseBody":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"deliveredAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"attemptLog":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","description":"1 para a primeira tentativa"},"signedAt":{"type":"integer","description":"Epoch em segundos usado na assinatura desta tentativa"},"signature":{"type":"string","description":"Valor `v1` do header X-Webhook-Signature desta tentativa"},"responseStatus":{"type":"integer","nullable":true},"responseBody":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"durationMs":{"type":"integer","nullable":true,"description":"Duração da requisição — separa recusa rápida de timeout"},"createdAt":{"type":"string"}},"required":["attempt","signedAt","signature","responseStatus","responseBody","errorMessage","durationMs","createdAt"],"additionalProperties":false},"description":"Histórico tentativa a tentativa, em ordem crescente. Os campos `responseStatus`/`responseBody`/`errorMessage` acima são apenas o resumo da ÚLTIMA tentativa — cada nova sobrescreve a anterior. Vazio nas entregas anteriores a este recurso."}},"required":["id","eventType","eventId","status","attempts","payload","responseStatus","responseBody","errorMessage","deliveredAt","createdAt","attemptLog"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"required":["statusCode","error","message"],"additionalProperties":false,"description":"Erro padrão da API"}}}}}}},"/v1/webhooks/backfill":{"post":{"summary":"Reenvia webhooks de um período (backfill)","tags":["Webhooks"],"description":"Dispara o webhook das notas de um período que ainda não foram comunicadas — tipicamente as emitidas ANTES de você cadastrar o endpoint.\n\nUse `dryRun: true` PRIMEIRO para ver quantas notas seriam atingidas: cada uma vira um POST no seu servidor, e um período largo pode ser milhares.\n\nPor padrão (`onlyMissing: true`) pula as notas que já geraram alguma entrega, então repetir a chamada não duplica o que já saiu.\n\nO evento de cada nota é o do seu estado ATUAL. Teto de 5.000 notas por execução — acima disso a resposta traz `truncated: true` e você deve estreitar o período.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date-time","description":"Início do período (ISO 8601), pela data de emissão"},"to":{"type":"string","format":"date-time","description":"Fim do período (ISO 8601), inclusive"},"types":{"type":"array","items":{"type":"string","enum":["NFE","NFCE","NFSE"]},"description":"Filtra por tipo. Omitido = todos"},"onlyMissing":{"type":"boolean","description":"Só notas que nunca geraram entrega (default true). false redispara tudo no período."},"environment":{"type":"string","enum":["PRODUCTION","HOMOLOGATION"],"description":"Escopo de ambiente. Omitido = ambos"},"dryRun":{"type":"boolean","description":"Só conta as notas atingidas, sem disparar nada"}},"required":["from","to"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","enum":[true]},"matched":{"type":"number","description":"Notas que seriam atingidas"},"truncated":{"type":"boolean","description":"true se excede o teto de 5.000 por execução"}},"required":["dryRun","matched","truncated"],"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"ID do run no Trigger.dev"},"matched":{"type":"number","description":"Notas encontradas no período"},"truncated":{"type":"boolean"}},"required":["runId","matched","truncated"],"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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)"},"details":{"type":"array","items":{"type":"string"},"description":"Lista completa de problemas quando há mais de um (ex: pendências de configuração na pré-validação da emissão). `message` traz o primeiro deles."}},"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"},{"name":"Clients","description":"Clientes (tomadores/destinatários) da empresa — referenciáveis por `clientId` ao criar documentos"},{"name":"Accounting","description":"MODO CONTADOR — exige a chave do ESCRITÓRIO (`ok_...`), não a da empresa. Carteira (empresas com vínculo ativo), fechamento fiscal em lote e notas recebidas (DF-e) de cada empresa-cliente. Escritório suspenso ou empresa sem vínculo ativo = 403"},{"name":"Received Documents","description":"Notas RECEBIDAS (DF-e): emitidas contra o CNPJ da empresa pelos fornecedores — listagem, XML, DANFE, sincronização e manifestação do destinatário (MD-e)"},{"name":"Templates","description":"Templates fiscais (NF-e/NFS-e) — pré-preenchem natureza/CFOP/ICMS/serviço; aplicáveis por `templateId` ao criar documentos"}]}