# NFS E

Emissão, cancelamento, correção e sincronização de NFS-e.

Fluxo típico:

1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.
2. Acompanhe via webhook ou `GET /nfse/{id}`.
3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.
4. Para cancelar autorizada: `POST /nfse/cancel`.
5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`.

## Listar NFS-e

> Lista NFS-e com suporte a filtros, paginação por cursor e seleção de campos.\
> \
> Campos disponíveis para seleção via \`fields\`:\
> \- \`id\`, \`protocol\`, \`nfse\_number\`, \`batch\_number\`, \`rps\`, \`dps\`, \`external\_id\`, \`link\`\
> \- \`issuer.legal\_name\`, \`issuer.name\`, \`issuer.tax\_id\`, \`issuer.address.city\`, \`issuer.address.municipality\`, \`issuer.address.state\`, \`issuer.address.municipality\_code\`\
> \- \`status\`, \`operation\_status\`, \`is\_current\`, \`check\_pending\_at\`\
> \- \`integration\`, \`provider\`, \`environment\`\
> \- \`created\_at\`, \`updated\_at\`

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"NfseListResponse":{"type":"object","additionalProperties":false,"required":["items","paginate"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/NfseListItem"}},"paginate":{"$ref":"#/components/schemas/NfseCursorPaginateMeta"}}},"NfseListItem":{"type":"object","additionalProperties":false,"description":"Item retornado na listagem de NFS-e. Os campos disponíveis dependem do parâmetro `fields`; `operation_control` é calculado pela API para controle operacional.","properties":{"id":{"type":"string"},"company_id":{"type":"string","description":"Identificador da empresa emissora da NFS-e."},"protocol":{"type":["string","null"]},"nfse_number":{"type":["string","null"]},"batch_number":{"type":["integer","null"],"description":"Número do lote de envio atribuído para providers que usam envio em lote."},"rps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores RPS da emissão municipal, quando aplicável.","properties":{"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]},"batch":{"type":["integer","null"]}}},"dps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores DPS da emissão nacional, quando aplicável.","properties":{"identifier":{"type":["string","null"]},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]}}},"external_id":{"type":"string"},"authorization":{"type":["string","null"],"description":"Código de verificação retornado pelo provider municipal. No Nacional, a chave fiscal fica em `access_key`."},"access_key":{"type":["string","null"],"description":"Chave de acesso da NFS-e (50 dígitos no padrão nacional, quando disponível no municipal)."},"link":{"type":["string","null"],"description":"Link de verificação da NFS-e no portal do município."},"integration":{"type":"string","enum":["municipal","national"]},"provider":{"type":["string","null"]},"environment":{"type":"string","enum":["production","homologation"]},"status":{"type":"string","enum":["created","processing","authorized","rejected","canceled","substituted","error","unsynced"]},"operation_status":{"type":["string","null"],"description":"Situação operacional. null = nenhuma operação em andamento; `cancellation_error` indica falha terminal de cancelamento com nova tentativa permitida quando `operation_control.can_cancel=true`, inclusive em registros legados `unsynced`.","enum":[null,"sync_pending","cancellation_pending","cancellation_error","substitution_pending"]},"operation_control":{"$ref":"#/components/schemas/NfseOperationControl"},"is_current":{"type":"boolean"},"check_pending_at":{"type":["string","null"],"format":"date-time"},"issuer":{"type":"object","properties":{"legal_name":{"type":"string"},"name":{"type":"string"},"tax_id":{"type":"string"},"address":{"type":"object","properties":{"municipality":{"type":"string"},"state":{"type":"string"},"municipality_code":{"type":["string","null"]}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NfseOperationControl":{"type":"object","additionalProperties":false,"required":["current_operation","can_cancel","can_interrupt","interrupt_available_at","elapsed_ms"],"properties":{"current_operation":{"type":["string","null"],"description":"Operação local acompanhada pela API no momento.","enum":[null,"send","cancel","substitute","post_send_verification","document_reconciliation","cancellation_reconciliation"]},"can_cancel":{"type":"boolean","description":"Indica se a interface pode liberar a ação de cancelamento para a NFS-e, considerando status local, operação ativa e capability do provedor."},"can_interrupt":{"type":"boolean","description":"Indica se a interface pode liberar a ação de interromper operação."},"interrupt_available_at":{"type":["string","null"],"format":"date-time","description":"Instante em que a interrupção fica disponível. Para `post_send_verification`, corresponde à janela de atenção de 5 minutos."},"elapsed_ms":{"type":["integer","null"],"minimum":0,"description":"Tempo decorrido desde o início da operação acompanhada, em milissegundos."}}},"NfseCursorPaginateMeta":{"type":"object","additionalProperties":false,"required":["limit","has_next_page","has_previous_page","start_cursor","end_cursor"],"properties":{"limit":{"type":"integer","minimum":10,"maximum":500},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":["string","null"]},"end_cursor":{"type":["string","null"]}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse":{"get":{"operationId":"listNfses","tags":["NFS-e"],"summary":"Listar NFS-e","description":"Lista NFS-e com suporte a filtros, paginação por cursor e seleção de campos.\n\nCampos disponíveis para seleção via `fields`:\n- `id`, `protocol`, `nfse_number`, `batch_number`, `rps`, `dps`, `external_id`, `link`\n- `issuer.legal_name`, `issuer.name`, `issuer.tax_id`, `issuer.address.city`, `issuer.address.municipality`, `issuer.address.state`, `issuer.address.municipality_code`\n- `status`, `operation_status`, `is_current`, `check_pending_at`\n- `integration`, `provider`, `environment`\n- `created_at`, `updated_at`","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"},{"name":"q","in":"query","required":false,"description":"Busca textual por external_id, protocolo, número ou tax_id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filtro por status da NFS-e.","schema":{"type":"string","enum":["created","processing","authorized","rejected","canceled","substituted","error","unsynced"]}},{"name":"operation_status","in":"query","required":false,"description":"Filtro por status de operação. Omitir ou enviar vazio para filtrar por nenhuma operação (null).","schema":{"type":"string","enum":["sync_pending","cancellation_pending","cancellation_error","substitution_pending","none"]}},{"name":"company_id","in":"query","required":false,"description":"Filtro por empresa. Chave de empresa ignora este filtro.","schema":{"$ref":"#/components/schemas/ObjectId"}},{"name":"integration","in":"query","required":false,"description":"Filtro pelo tipo de integração (`municipal` ou `national`).","schema":{"type":"string","enum":["municipal","national"]}},{"name":"provider","in":"query","required":false,"description":"Filtro pelo provedor fiscal vinculado à empresa emissora (ex.: `sigssis`).","schema":{"type":"string"}},{"name":"municipality","in":"query","required":false,"description":"Filtro pelo nome do município da empresa emissora (ex.: `Chapecó`).","schema":{"type":"string"}},{"name":"municipality_code","in":"query","required":false,"description":"Filtro pelo código IBGE do município da empresa emissora.","schema":{"type":"string","pattern":"^\\d{7}$"}},{"name":"state","in":"query","required":false,"description":"Filtro pela UF da empresa emissora (sigla de 2 letras, ex.: `SC`).","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","required":false,"description":"Data inicial (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"end_at","in":"query","required":false,"description":"Data final (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"description":"Cursor opaco de paginação.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página (10 a 500).","schema":{"type":"integer","minimum":10,"maximum":500,"default":10}},{"name":"fields","in":"query","required":false,"description":"Campos retornados separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de NFS-e","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseListResponse"}}}},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Enviar NFS-e

> Envia uma ou mais NFS-e para emissão.\
> \
> \## Como integrar\
> \- Envie um array com 1 a 500 documentos. Cada item cria uma NFS-e independente.\
> \- Cada documento representa um serviço fiscal único. Se o ERP tiver vários itens comerciais, consolide a descrição em \`service.description\`, \`service.additional\_information\` ou campos documentais específicos.\
> \- Informe apenas dados de emissão. Não envie número da NFS-e, protocolo, lote, URLs de XML/DANFSe ou outros campos gerados pela plataforma/provedor.\
> \- \`issuer.tax\_id\` deve pertencer ao workspace da chave usada. Com chave de empresa, ele deve ser o CNPJ vinculado à própria integração.\
> \- O cadastro da empresa emissora fornece os demais dados do prestador, como endereço, Inscrição Municipal, certificado e configuração NFS-e.\
> \- Após o envio, acompanhe por webhook ou \`GET /nfse/{id}\`.\
> \
> \## Campos preferenciais\
> \- Use \`series\` na raiz quando precisar direcionar uma série fiscal específica.\
> \- Use \`emission\_datetime\` e \`competence\_date\` na raiz. Quando ausentes, a API usa a data/hora atual do POST para emissão e competência.\
> \- Use \`address.city\` como cidade/localidade em endereços do tomador, intermediário, obra/evento e IBS/CBS.\
> \- Use \`service.national\_tax\_code\` para o código nacional de tributação (\`cTribNac\`) e \`service.municipal\_tax\_code\` para o código municipal de serviço.\
> \- Quando \`service.incidence\_municipality\_code\` vier vazio, a API usa o código IBGE do endereço da empresa emissora.\
> \
> \## Compatibilidade para integrações antigas\
> A API ainda aceita aliases declarados na spec de aliases HTTP de NFS-e, sempre antes do processamento fiscal. Quando o alias e o campo canônico vierem juntos, o campo canônico vence.\
> \
> \- \`rps.series\` e \`dps.series\` são \*\*Compatibilidade.\*\* (Compatibility) de entrada para \`series\`.\
> \- \`rps.type\` e \`dps.type\` são \*\*Uso desaconselhado.\*\* (Discouraged) de entrada; a API aceita e descarta esses valores.\
> \- \`competence\_datetime\`, \`service.emission\_datetime\`, \`service.competence\_date\` e \`service.competence\_datetime\` são \*\*Compatibilidade.\*\* (Compatibility) de entrada para as datas raiz.\
> \- \`address.municipality\` é \*\*Compatibilidade.\*\* (Compatibility) de entrada e saída para \`address.city\`.\
> \- \`service.national\_code\` é \*\*Compatibilidade.\*\* (Compatibility) de entrada para \`service.national\_tax\_code\`.\
> \- Aliases IBS/CBS antigos são aceitos somente na entrada e normalizados para o schema canônico \`NfseIbscbs\`:\
>   \`ibscbs.property.cib\`, \`ibscbs.property.codigoCIB\`, \`state\_region\`, \`estadoProvinciaRegiao\`, \`postal\_address\_code\`, \`foreign\_postal\_code\`, \`taxation.deferment\`, \`taxation.tax\_situation\_code\`, \`taxation.classification\_code\`, \`national\_dfe\`, \`fiscal\_document\` e \`document\`.\
> \
> \## Nacional, municipal e IBS/CBS\
> \- No fluxo municipal, a API escolhe o provedor fiscal pela configuração NFS-e salva na empresa emissora.\
> \- No Ambiente Nacional, a API serializa os campos nacionais informados e deixa obrigatoriedade, formato e combinações fiscais para a rejeição oficial do webservice nacional.\
> \- Em provedores municipais aderentes ao IBS/CBS, a API envia os campos fiscais recebidos quando o layout do provedor os suporta. Campos ausentes ou inválidos devem voltar como rejeição oficial da prefeitura/provedor.\
> \
> \## Substituição\
> \- Para substituir uma NFS-e autorizada, envie \`substituted\_reference\` com \`nfse\_id\` ou \`external\_id\`.\
> \- Quando usar \`substituted\_reference.external\_id\`, o \`issuer.tax\_id\` do próprio payload define a empresa da busca.\
> \- A nota original fica autorizada em estado transitório até a conclusão. Se a substituta autorizar, a original passa para \`substituted\`; se falhar ou for rejeitada, a original volta ao estado anterior.\
> \- O \`external\_id\` pode ser reaproveitado na substituição; a unicidade é aplicada ao documento atual.\
> \
> \## Sandbox\
> Use \`<https://sandbox.api.edocs.ixcsoft.com.br\\`> para testar sem emissão fiscal real. Nenhuma requisição é enviada à prefeitura ou ao Ambiente Nacional; a plataforma simula autorização e gera XML/DANFSe de teste. \`environment\` continua aceitando apenas \`production\` ou \`homologation\`, e cenários de rejeição, timeout ou pendência não são controlados por valores fiscais do payload.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"CreateNfsesRequest":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/NfseDocument"}},"NfseDocument":{"type":"object","additionalProperties":false,"required":["external_id","issuer"],"properties":{"external_id":{"type":"string","description":"Identificador externo do documento."},"emission_datetime":{"type":"string","format":"date-time","description":"Data/hora de emissão do documento. Campo raiz canônico para `DataEmissao`; deve ser datetime ISO 8601 com fuso explícito."},"competence_date":{"type":"string","description":"Data de competência do documento. Campo raiz canônico para `Competencia`; pode ser data ou datetime aceito pelo template do provider."},"issuer":{"$ref":"#/components/schemas/NfseIssuer","description":"Prestador do serviço."},"customer":{"$ref":"#/components/schemas/NfseCustomer","description":"Tomador do serviço."},"intermediary":{"$ref":"#/components/schemas/NfseIntermediary","description":"Intermediário do serviço, quando existir. Usa o padrão e-docs de identificação, endereço, telefone e e-mail."},"series":{"type":"string","minLength":1,"description":"Série fiscal opcional. A API decide como serializar a série conforme o provider efetivo da empresa."},"rps":{"type":"object","additionalProperties":false,"description":"**Compatibilidade.** (Compatibility) Alias permanente de entrada HTTP. Em código novo, use `series` na raiz; `rps.series` é normalizado para `series` e `rps.type` legado é descartado sem efeito fiscal.","properties":{"series":{"type":"string","description":"Série fiscal municipal. Normalizada para `series` na raiz antes do processamento."},"type":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"**Uso desaconselhado.** (Discouraged) Campo legado aceito apenas por compatibilidade de entrada HTTP; o valor é descartado antes do processamento fiscal."}}},"dps":{"type":"object","additionalProperties":false,"description":"**Compatibilidade.** (Compatibility) Alias permanente de entrada HTTP. Em código novo, use `series` na raiz; `dps.series` é normalizado para `series` e `dps.type` legado é descartado sem efeito fiscal.","properties":{"series":{"type":"string","pattern":"^\\d{1,5}$","description":"Série fiscal nacional. Normalizada para `series` na raiz antes do processamento."},"type":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"**Uso desaconselhado.** (Discouraged) Campo legado aceito apenas por compatibilidade de entrada HTTP; o valor é descartado antes do processamento fiscal."}}},"send_email":{"type":"boolean","description":"Define se DANFSe e XML da NFS-e serão enviados por email para o tomador."},"substituted_reference":{"$ref":"#/components/schemas/NfseSubstitutedReference","description":"Referência da nota autorizada que será substituída."},"cancel_code":{"type":"integer","description":"Código de cancelamento serializado quando informado; domínio fiscal é validado pelo provedor."},"cancel_reason":{"type":"string","description":"Motivo de cancelamento serializado quando informado; obrigatoriedade e tamanho são validados pelo provedor."},"service":{"type":"object","additionalProperties":false,"description":"Dados do serviço prestado.","required":["description"],"properties":{"description":{"type":"string","description":"Descrição dos serviços da nota fiscal."},"cnae_code":{"type":"string","description":"Código CNAE com 7 dígitos. Use quando o layout fiscal efetivo exigir; não é usado no perfil `national`."},"national_tax_code":{"type":"string","description":"Código nacional de tributação do serviço (`cTribNac`). A serialização vem do template e a obrigatoriedade fiscal deve voltar como rejeição oficial do provedor."},"national_code":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias de entrada aceito somente em requests de criação para integrações antigas; a API normaliza para `national_tax_code` antes do processamento fiscal e respostas públicas usam apenas `national_tax_code`."},"operation_nature":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Natureza da operação fiscal do serviço usada por providers municipais com tag própria, como `NaturezaOperacao`. O domínio é específico do layout municipal e não representa a exigibilidade canônica do ISS."},"lc116_code":{"type":"string","description":"Código do item da lista de serviços da LC 116/2003. Em providers ABRASF/SigSSIS, alimenta `ItemListaServico` e não substitui `municipal_tax_code`."},"municipal_tax_code":{"type":"string","description":"Código de serviço municipal (`cTribMun`)."},"incidence_municipality_code":{"type":"string","description":"Município de incidência do ISS. A aceitação fiscal depende do provedor."},"country_code":{"type":"string","description":"País da prestação do serviço. A aceitação fiscal depende do provedor."},"nbs_code":{"type":"string","description":"Código NBS serializado quando o template do provedor consumir esse campo."},"taxpayer_code":{"type":"string","description":"Código interno do contribuinte para identificar o serviço no ambiente fiscal quando o layout aceitar esse identificador."},"technical_document_id":{"type":"string","description":"Documento de responsabilidade técnica associado ao serviço, como ART, RRT ou documento técnico equivalente aceito pelo provider."},"reference_document":{"type":"string","description":"Documento fiscal, contratual ou administrativo usado como referência da prestação."},"purchase_order_number":{"type":"string","description":"Número de pedido, ordem de serviço, projeto ou referência comercial que identifica a contratação."},"additional_information":{"type":"string","description":"Informações complementares da nota fiscal."},"event":{"$ref":"#/components/schemas/NfseServiceEvent","description":"Dados de evento relacionado ao serviço."},"construction":{"$ref":"#/components/schemas/NfseServiceConstruction","description":"Dados de obra ou construção civil relacionados ao serviço."},"foreign_trade":{"$ref":"#/components/schemas/NfseServiceForeignTrade","description":"Dados de comércio exterior quando o serviço envolver operação internacional."}}},"taxes":{"type":"object","description":"Dados tributários do serviço.","properties":{"iss_taxation":{"oneOf":[{"type":"string","enum":["1","2","3","4","5","6","7"]},{"type":"integer","enum":[1,2,3,4,5,6,7]}],"description":"Tributação do ISSQN no contrato canônico:\n- `1`: operação tributável ou exigível\n- `2`: imunidade ou não incidência, conforme a integração aplicável\n- `3`: exportação de serviço ou isenção, conforme a integração aplicável\n- `4`: não incidência ou exportação, conforme a integração aplicável\n- `5`: imunidade\n- `6`: exigibilidade suspensa por decisão judicial\n- `7`: exigibilidade suspensa por processo administrativo\n\nNa entrada HTTP, também aceita o inteiro equivalente (`1` a `7`) e normaliza para string antes do processamento fiscal.\nObrigatoriedade, tamanho, faixa e domínio fiscal devem voltar como rejeição oficial do provedor."},"iss_retention_type":{"oneOf":[{"type":"string","enum":["1","2","3"]},{"type":"integer","enum":[1,2,3]}],"description":"Retenção do ISSQN no Ambiente Nacional e em providers municipais aderentes ao IBS/CBS:\n- `1`: não retido\n- `2`: retido pelo tomador\n- `3`: retido pelo intermediário\n\nNa entrada HTTP, também aceita o inteiro equivalente (`1` a `3`) e normaliza para string antes do processamento fiscal.\nEm providers municipais aderentes ao IBS/CBS, o runtime deriva `IssRetido` e `ResponsavelRetencao` a partir deste campo quando o provider declarar exigência."},"social_retention_type":{"oneOf":[{"type":"string","enum":["0","1","2","3","4","5","6","7","8","9"]},{"type":"integer","enum":[0,1,2,3,4,5,6,7,8,9]}],"description":"Tipo de retenção social para PIS/COFINS:\n- `0`: não retido\n- `1`: retido pelo tomador\n- `2`: retido pelo prestador\n- `3` a `9`: demais tipos conforme padrão Nacional ADN v1.01\n\nNa entrada HTTP, também aceita o inteiro equivalente (`0` a `9`) e normaliza para string antes do processamento fiscal.\nA aceitação fiscal final deve voltar como rejeição oficial do provedor."},"pis_cofins_cst":{"oneOf":[{"type":"string","enum":["00","01","02","03","04","05","06","07","08","09","49","50","51","52","53","54","55","56","60","61","62","63","64","65","66","67","70","71","72","73","74","75","98","99"]},{"type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,49,50,51,52,53,54,55,56,60,61,62,63,64,65,66,67,70,71,72,73,74,75,98,99]}],"description":"CST opcional de PIS/COFINS usado pelo Ambiente Nacional e por providers municipais que serializam o bloco social do XML:\n- `00`: nenhum\n- `01`: operação tributável com alíquota básica\n- `02`: operação tributável com alíquota diferenciada\n- `03`: operação tributável por unidade de medida\n- `04`: operação tributável monofásica com alíquota zero\n- `05`: operação tributável por substituição tributária\n- `06`: operação tributável a alíquota zero\n- `07`: operação tributável da contribuição\n- `08`: operação sem incidência\n- `09`: operação com suspensão da contribuição\n- `49`, `50` a `56`, `60` a `67`, `70` a `75`, `98` e `99`: demais CSTs oficiais de PIS/COFINS\n\nNa entrada HTTP, também aceita o inteiro equivalente; valores `0` a `9` são normalizados para `00` a `09` antes do processamento fiscal.\nNo municipal, a serialização depende do template anotado."},"result_country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"País onde ocorre o resultado da exportação do serviço, quando exigido pelo layout fiscal."},"immunity_type":{"type":"string","description":"Tipo de imunidade do ISSQN quando a tributação do serviço indicar imunidade."},"suspension_type":{"type":"string","description":"Tipo de suspensão da exigibilidade do ISSQN, judicial ou administrativa, conforme o layout fiscal."},"suspension_process_number":{"type":"string","description":"Número do processo judicial ou administrativo relacionado à suspensão da exigibilidade."},"municipal_benefit":{"$ref":"#/components/schemas/NfseMunicipalBenefit","description":"Benefício fiscal municipal aplicável ao ISSQN."},"estimated_tax_burden":{"$ref":"#/components/schemas/NfseEstimatedTaxBurden","description":"Tributos aproximados informados no documento fiscal."}}},"ibscbs":{"$ref":"#/components/schemas/NfseIbscbs","description":"Bloco IBS/CBS canônico da Reforma Tributária. Quando informado, o template do provedor serializa os campos suportados e omite ausentes; obrigatoriedade, tamanho, faixa e domínio fiscal devem voltar como rejeição oficial."},"values":{"$ref":"#/components/schemas/NfseValues","description":"Valores da nota fiscal."}}},"NfseIssuer":{"type":"object","additionalProperties":false,"required":["tax_id"],"properties":{"tax_id":{"type":"string","description":"Número do CNPJ do prestador (somente dígitos)."}}},"NfseCustomer":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","minLength":1,"description":"CPF ou CNPJ do tomador, somente dígitos. Para tomador estrangeiro, use `nif` ou `no_nif_reason` conforme o layout fiscal."},"municipal_registration":{"type":"string","description":"Inscrição Municipal do tomador."},"nif":{"type":"string","minLength":1,"description":"Número de identificação fiscal do tomador estrangeiro."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo da ausência de NIF do tomador estrangeiro quando o layout fiscal permitir."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física do tomador."},"legal_name":{"type":"string","description":"Razão social ou nome do tomador."},"name":{"type":"string","description":"Nome fantasia do tomador."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço completo do tomador."},"phone":{"type":"string","description":"Telefone de contato do tomador."},"email":{"type":"string","format":"email","description":"E-mail de contato do tomador."}}},"NfseAddress":{"type":"object","additionalProperties":false,"properties":{"street":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Logradouro. Não aceita símbolos especiais nem quebra de linha."},"number":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Número do endereço. Não aceita símbolos especiais nem quebra de linha."},"neighborhood":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Bairro. Não aceita símbolos especiais nem quebra de linha."},"municipality":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias permanente de `city`.\nAceito na entrada HTTP e devolvido nas respostas para manter integrações existentes.\nNão é usado por providers, templates, workers ou DANFSe."},"city":{"type":"string","description":"Cidade/localidade do endereço. Campo canônico do contrato NFS-e."},"state":{"type":"string","maxLength":2,"description":"UF brasileira ou estado/província/região estrangeira."},"postal_code":{"type":"string","minLength":1,"pattern":"^(?:\\d{8}|\\d{5}-\\d{3})$","description":"CEP brasileiro ou código postal exterior."},"complement":{"type":"string","description":"Complemento do endereço."},"municipality_code":{"type":"string","maxLength":7,"description":"Código IBGE do município brasileiro, usado para serialização fiscal quando aplicável."},"country":{"type":"string","maxLength":60,"description":"Nome do país, quando útil para exibição."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."}}},"NfseIntermediary":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física, somente dígitos."},"municipal_registration":{"type":"string","description":"Inscrição Municipal."},"legal_name":{"type":"string","description":"Razão social ou nome."},"name":{"type":"string","description":"Nome fantasia ou alias aceito."},"address":{"$ref":"#/components/schemas/NfseAddress"},"phone":{"type":"string","description":"Telefone de contato."},"email":{"type":"string","format":"email","description":"E-mail de contato."},"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município."}}},"NfseSubstitutedReference":{"oneOf":[{"type":"object","additionalProperties":false,"required":["nfse_id"],"properties":{"nfse_id":{"$ref":"#/components/schemas/ObjectId","description":"ID interno da NFS-e autorizada que será substituída."}}},{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","description":"ID externo da NFS-e autorizada que será substituída no mesmo emissor."}}}],"description":"Aceita exatamente um identificador (`nfse_id` ou `external_id`)."},"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"NfseServiceEvent":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","description":"Nome do evento relacionado ao serviço."},"identifier":{"type":"string","description":"Identificador do evento."},"description":{"type":"string","description":"Descrição do evento."},"start_date":{"type":"string","format":"date","description":"Data de início do evento."},"end_date":{"type":"string","format":"date","description":"Data de encerramento do evento."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço do evento."}}},"NfseServiceConstruction":{"type":"object","additionalProperties":false,"properties":{"work_code":{"type":"string","description":"Código da obra."},"cib_code":{"type":"string","description":"Código do Cadastro Imobiliário Brasileiro."},"property_registration":{"type":"string","description":"Inscrição imobiliária da obra."},"art":{"type":"string","description":"Anotação, registro ou termo de responsabilidade técnica da obra."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço da obra."}}},"NfseServiceForeignTrade":{"type":"object","additionalProperties":false,"properties":{"provision_mode":{"type":"string","description":"Modo de prestação no comércio exterior."},"relationship_type":{"type":"string","description":"Tipo de vínculo entre prestador e tomador no exterior."},"currency_code":{"type":"string","description":"Código da moeda da operação."},"foreign_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do serviço na moeda estrangeira."},"issuer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo prestador."},"customer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo tomador."},"temporary_goods_movement":{"type":"string","description":"Indicador de movimentação temporária de bens vinculada ao serviço."},"import_declaration_number":{"type":"string","description":"Número da declaração de importação relacionada ao serviço."},"export_registration_number":{"type":"string","description":"Número do registro de exportação relacionado ao serviço."},"mdic_sharing":{"type":"string","description":"Indicador de compartilhamento com o MDIC quando exigido pelo layout fiscal."}}},"NfseDecimalValue":{"oneOf":[{"type":"number"},{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$"}],"description":"Valor decimal aceito como número JSON ou string numérica decimal."},"NfseMunicipalBenefit":{"type":"object","additionalProperties":false,"properties":{"identifier":{"type":"string","pattern":"^[0-9]{14}$","description":"Identificador do benefício fiscal municipal, com 14 dígitos quando serializado no layout nacional."},"base_reduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de redução da base de cálculo concedido pelo benefício."},"base_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Percentual de redução da base de cálculo concedido pelo benefício."}}},"NfseEstimatedTaxBurden":{"type":"object","additionalProperties":false,"properties":{"federal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos federais."},"state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos estaduais."},"municipal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos municipais."},"federal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos federais."},"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos estaduais."},"municipal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos municipais."},"simple_national_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":99.99,"description":"Alíquota aproximada dos tributos para optante do Simples Nacional."}}},"NfseIbscbs":{"type":"object","additionalProperties":false,"description":"Bloco IBS/CBS compartilhado entre o Ambiente Nacional e provedores municipais aderentes ao IBS/CBS.\n`tax_situation_code` e `classification_code` são o CST/cClassTrib principal do IBS/CBS. O grupo `taxation.regular.*` representa a tributação regular e não é duplicidade desses campos principais.\nNo `national`, envie apenas os campos declaratórios do layout nacional: `purpose`, `final_consumer`, `operation_indicator`, `operation_type`, `government_entity_type`, `destination_indicator`, `references`, `tax_situation_code`/`classification_code`, `destination`, `property`, `taxation` e `reimbursements`.\nOs campos `reduction_rate`, `incidence_location_code`, `incidence_location_name`, `values` e `totals` existem no contrato canônico para provedores municipais aderentes ao IBS/CBS, mas são rejeitados pelo provedor Nacional quando a empresa usa `integration=national`.\nNão envie `ibscbs.taxation.tax_situation_code` nem `ibscbs.taxation.classification_code`; esses aliases são aceitos somente na borda HTTP do `POST /nfse` para compatibilidade de entrada e são normalizados para os campos principais.","properties":{"purpose":{"type":"string","enum":["0"],"description":"Finalidade da NFS-e no bloco IBS/CBS. No XSD nacional atual, apenas `0` é aceito."},"final_consumer":{"type":"string","enum":["0","1"],"description":"Indicador de consumidor final no bloco IBS/CBS. Opcional no XSD nacional."},"operation_indicator":{"type":"string","pattern":"^[0-9]{6}$","description":"Código do indicador da operação no bloco IBS/CBS."},"operation_type":{"type":"string","enum":["1","2","3","4","5"],"description":"Tipo da operação no bloco IBS/CBS."},"government_entity_type":{"type":"string","enum":["1","2","3","4"],"description":"Tipo de ente governamental no bloco IBS/CBS."},"destination_indicator":{"type":"string","enum":["0","1"],"description":"Indicador do destino da operação no bloco IBS/CBS."},"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST principal aplicado ao bloco IBS/CBS. Não confundir com `taxation.regular.tax_situation_code`, que pertence ao grupo de tributação regular."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib principal usado no bloco IBS/CBS. Não confundir com `taxation.regular.classification_code`, que pertence ao grupo de tributação regular."},"reduction_rate":{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$","description":"Percentual redutor serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_code":{"type":"string","description":"Código do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_name":{"type":"string","description":"Nome do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"references":{"type":"array","description":"Referências técnicas aceitas pelo layout IBS/CBS.","items":{"type":"string"}},"destination":{"$ref":"#/components/schemas/NfseIbscbsDestination","description":"Destinatário do serviço no grupo declaratório IBS/CBS do Ambiente Nacional."},"property":{"$ref":"#/components/schemas/NfseIbscbsProperty","description":"Informações de imóvel no grupo declaratório IBS/CBS do Ambiente Nacional."},"taxation":{"$ref":"#/components/schemas/NfseIbscbsTaxation","description":"Subgrupos declaratórios de tributação IBS/CBS. Não contém o CST/cClassTrib principal; esses campos ficam em `ibscbs.tax_situation_code` e `ibscbs.classification_code`."},"reimbursements":{"type":"array","maxItems":1000,"description":"Documentos de reembolso, repasse ou ressarcimento no grupo declaratório IBS/CBS.","items":{"$ref":"#/components/schemas/NfseIbscbsReimbursement"}},"values":{"$ref":"#/components/schemas/NfseIbscbsValues","description":"Valores calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."},"totals":{"$ref":"#/components/schemas/NfseIbscbsTotals","description":"Totais calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."}}},"NfseIbscbsDestination":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome do destinatário."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress"},"phone":{"type":"string","description":"Telefone do destinatário."},"email":{"type":"string","format":"email","description":"E-mail do destinatário."}}},"NfseIbscbsAddress":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município para endereço nacional."},"postal_code":{"type":"string","description":"CEP brasileiro ou código postal exterior."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."},"municipality":{"type":"string","description":"Município/localidade do endereço no contrato canônico NFS-e."},"state":{"type":"string","description":"UF brasileira ou estado/província/região estrangeira."},"street":{"type":"string","description":"Logradouro."},"number":{"type":"string","description":"Número do endereço."},"complement":{"type":"string","description":"Complemento do endereço."},"neighborhood":{"type":"string","description":"Bairro."}}},"NfseIbscbsProperty":{"type":"object","additionalProperties":false,"properties":{"registration_code":{"type":"string","description":"Inscrição imobiliária fiscal."},"cib_code":{"type":"string","minLength":8,"maxLength":8,"description":"Código do Cadastro Imobiliário Brasileiro."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress","description":"Endereço do imóvel. No Nacional, informe `cib_code` ou `address`, nunca ambos."}}},"NfseIbscbsTaxation":{"type":"object","additionalProperties":false,"description":"Subgrupos declaratórios de tributação IBS/CBS. `regular` é tributação regular distinta dos campos principais do bloco.","properties":{"credit_presumed_code":{"type":"string","pattern":"^[0-9]{2}$","description":"Código de crédito presumido IBS/CBS."},"regular":{"$ref":"#/components/schemas/NfseIbscbsRegularTaxation","description":"Tributação regular IBS/CBS, distinta do CST/cClassTrib principal do bloco."},"deferral":{"$ref":"#/components/schemas/NfseIbscbsDeferral"}}},"NfseIbscbsRegularTaxation":{"type":"object","additionalProperties":false,"properties":{"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST da tributação regular. Campo distinto de `ibscbs.tax_situation_code`."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib da tributação regular. Campo distinto de `ibscbs.classification_code`."}}},"NfseIbscbsDeferral":{"type":"object","additionalProperties":false,"properties":{"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS estadual."},"municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS municipal."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento da CBS."}}},"NfseIbscbsReimbursement":{"type":"object","additionalProperties":false,"properties":{"dfe_national":{"$ref":"#/components/schemas/NfseIbscbsDfeNational"},"other_fiscal_document":{"$ref":"#/components/schemas/NfseIbscbsOtherFiscalDocument"},"other_document":{"$ref":"#/components/schemas/NfseIbscbsOtherDocument"},"supplier":{"$ref":"#/components/schemas/NfseIbscbsIdentity"},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento referenciado."},"competence_date":{"type":"string","format":"date","description":"Data de competência do documento referenciado."},"type":{"type":"string","enum":["01","02","03","04","99"],"description":"Tipo de reembolso, repasse ou ressarcimento."},"type_description":{"type":"string","description":"Descrição quando `type` for `99`."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do reembolso, repasse ou ressarcimento."}}},"NfseIbscbsDfeNational":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","9"],"description":"Tipo de chave do documento fiscal eletrônico nacional."},"type_description":{"type":"string","description":"Descrição quando `type` for `9`."},"key":{"type":"string","maxLength":50,"description":"Chave do documento fiscal eletrônico."}}},"NfseIbscbsOtherFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código do município emissor do documento fiscal."},"number":{"type":"string","description":"Número do documento fiscal."},"description":{"type":"string","description":"Descrição do documento fiscal."}}},"NfseIbscbsOtherDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento não fiscal."},"description":{"type":"string","description":"Descrição do documento não fiscal."}}},"NfseIbscbsIdentity":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome."}}},"NfseIbscbsValues":{"type":"object","additionalProperties":false,"description":"Valores calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo do IBS/CBS."},"state":{"$ref":"#/components/schemas/NfseIbscbsStateValues"},"municipality":{"$ref":"#/components/schemas/NfseIbscbsMunicipalityValues"},"federal":{"$ref":"#/components/schemas/NfseIbscbsFederalValues"}}},"NfseIbscbsStateValues":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota estadual do IBS."},"ibs_state_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota estadual do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_state_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva estadual do IBS."}}},"NfseIbscbsMunicipalityValues":{"type":"object","additionalProperties":false,"properties":{"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota municipal do IBS."},"ibs_municipality_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota municipal do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_municipality_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva municipal do IBS."}}},"NfseIbscbsFederalValues":{"type":"object","additionalProperties":false,"properties":{"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota federal da CBS."},"cbs_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota federal da CBS em providers municipais aderentes ao IBS/CBS."},"cbs_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva federal da CBS."}}},"NfseIbscbsTotals":{"type":"object","additionalProperties":false,"description":"Totais calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"total_nf_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total da NFS-e usado no bloco IBS/CBS."},"ibs":{"$ref":"#/components/schemas/NfseIbscbsIbsTotals"},"cbs":{"$ref":"#/components/schemas/NfseIbscbsCbsTotals"},"government_purchase":{"$ref":"#/components/schemas/NfseIbscbsGovernmentPurchaseTotals"}}},"NfseIbscbsIbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado do IBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"state_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"},"municipality_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"}}},"NfseIbscbsCreditPresumedTotals":{"type":"object","additionalProperties":false,"properties":{"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de crédito presumido em providers municipais aderentes ao IBS/CBS."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de crédito presumido em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsIbsLocationTotal":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total consolidado do grupo correspondente."},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido do grupo correspondente em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsCbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado da CBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido da CBS em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsGovernmentPurchaseTotals":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota estadual do IBS em compra governamental."},"ibs_state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor estadual do IBS em compra governamental."},"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota municipal do IBS em compra governamental."},"ibs_municipality_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor municipal do IBS em compra governamental."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da CBS em compra governamental."},"cbs_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CBS em compra governamental."}}},"NfseValues":{"type":"object","additionalProperties":false,"required":["total_amount"],"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total do serviço."},"net_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor líquido do serviço."},"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota do ISS."},"iss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do ISS."},"unconditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto incondicional aplicado ao serviço."},"conditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto condicional aplicado ao serviço."},"ir_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do IR retido na fonte."},"pis_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do PIS retido na fonte."},"cofins_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da COFINS retida na fonte."},"inss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do INSS retido na fonte."},"csll_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CSLL retida na fonte."},"other_retentions":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Outras retenções aplicadas ao serviço."},"deductions_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total das deduções."},"intermediary_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor recebido pelo intermediário do serviço, quando o layout fiscal exigir esse destaque."},"cp_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de Contribuição Previdenciária retido."},"pis_cofins_base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo compartilhada para PIS e COFINS (vBCPisCofins no XML)."},"pis_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota do PIS (pAliqPis no XML)."},"cofins_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da COFINS (pAliqCofins no XML)."},"deductions":{"type":"array","maxItems":1000,"description":"Documentos fiscais usados para dedução ou redução da base de cálculo, quando o layout fiscal permitir.","items":{"$ref":"#/components/schemas/NfseDeduction"}}}},"NfseDeduction":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","4","5","6","7","8","9","99"],"description":"Tipo fiscal da dedução conforme o layout aplicável."},"description":{"type":"string","maxLength":150,"description":"Descrição da dedução ou redução."},"deductible_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do documento elegível à dedução."},"deduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor efetivamente deduzido."},"document_kind":{"type":"string","description":"Tipo de documento que comprova a dedução."},"nfse_key":{"type":"string","pattern":"^[0-9]{50}$","description":"Chave de acesso da NFS-e usada como documento de dedução, com 50 dígitos quando exigida pelo Nacional."},"nfe_key":{"type":"string","pattern":"^[0-9]{44}$","description":"Chave de acesso da NF-e usada como documento de dedução, com 44 dígitos quando exigida pelo Nacional."},"other_document_number":{"type":"string","maxLength":255,"description":"Número de outro documento aceito para dedução."},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento de dedução."},"municipal_nfse":{"$ref":"#/components/schemas/NfseDeductionMunicipalNfse"},"fiscal_document":{"$ref":"#/components/schemas/NfseDeductionFiscalDocument"},"supplier":{"$ref":"#/components/schemas/NfseIntermediary","description":"Fornecedor ou prestador associado ao documento de dedução."}}},"NfseDeductionMunicipalNfse":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município da NFS-e dedutível."},"number":{"type":"string","description":"Número da NFS-e dedutível."},"verification_code":{"type":"string","pattern":"^[a-zA-Z0-9]{1,9}$","description":"Código de verificação da NFS-e dedutível."}}},"NfseDeductionFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento fiscal dedutível."},"model":{"type":"string","description":"Modelo do documento fiscal dedutível."},"series":{"type":"string","description":"Série do documento fiscal dedutível."},"state":{"type":"string","maxLength":2,"description":"UF do documento fiscal dedutível."},"access_key":{"type":"string","description":"Chave de acesso do documento fiscal dedutível."}}},"CreateNfsesResponse":{"type":"array","description":"Resultado da criação das NFS-e.","items":{"$ref":"#/components/schemas/NfseCreatedResult"}},"NfseCreatedResult":{"type":"object","additionalProperties":false,"required":["id","nfse_outbox_id","workspace_id","company_id","external_id","issuer_tax_id"],"properties":{"id":{"type":"string","description":"Identificador da NFS-e criada."},"nfse_outbox_id":{"type":"string","description":"Identificador da NFS-e na fila de processamento."},"workspace_id":{"type":"string","description":"Identificador do workspace."},"company_id":{"type":"string","description":"Identificador da empresa emissora."},"external_id":{"type":"string","description":"Identificador externo informado no envio."},"issuer_tax_id":{"type":"string","description":"CNPJ do prestador (somente dígitos)."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse":{"post":{"operationId":"createNfses","tags":["NFS-e"],"summary":"Enviar NFS-e","description":"Envia uma ou mais NFS-e para emissão.\n\n## Como integrar\n- Envie um array com 1 a 500 documentos. Cada item cria uma NFS-e independente.\n- Cada documento representa um serviço fiscal único. Se o ERP tiver vários itens comerciais, consolide a descrição em `service.description`, `service.additional_information` ou campos documentais específicos.\n- Informe apenas dados de emissão. Não envie número da NFS-e, protocolo, lote, URLs de XML/DANFSe ou outros campos gerados pela plataforma/provedor.\n- `issuer.tax_id` deve pertencer ao workspace da chave usada. Com chave de empresa, ele deve ser o CNPJ vinculado à própria integração.\n- O cadastro da empresa emissora fornece os demais dados do prestador, como endereço, Inscrição Municipal, certificado e configuração NFS-e.\n- Após o envio, acompanhe por webhook ou `GET /nfse/{id}`.\n\n## Campos preferenciais\n- Use `series` na raiz quando precisar direcionar uma série fiscal específica.\n- Use `emission_datetime` e `competence_date` na raiz. Quando ausentes, a API usa a data/hora atual do POST para emissão e competência.\n- Use `address.city` como cidade/localidade em endereços do tomador, intermediário, obra/evento e IBS/CBS.\n- Use `service.national_tax_code` para o código nacional de tributação (`cTribNac`) e `service.municipal_tax_code` para o código municipal de serviço.\n- Quando `service.incidence_municipality_code` vier vazio, a API usa o código IBGE do endereço da empresa emissora.\n\n## Compatibilidade para integrações antigas\nA API ainda aceita aliases declarados na spec de aliases HTTP de NFS-e, sempre antes do processamento fiscal. Quando o alias e o campo canônico vierem juntos, o campo canônico vence.\n\n- `rps.series` e `dps.series` são **Compatibilidade.** (Compatibility) de entrada para `series`.\n- `rps.type` e `dps.type` são **Uso desaconselhado.** (Discouraged) de entrada; a API aceita e descarta esses valores.\n- `competence_datetime`, `service.emission_datetime`, `service.competence_date` e `service.competence_datetime` são **Compatibilidade.** (Compatibility) de entrada para as datas raiz.\n- `address.municipality` é **Compatibilidade.** (Compatibility) de entrada e saída para `address.city`.\n- `service.national_code` é **Compatibilidade.** (Compatibility) de entrada para `service.national_tax_code`.\n- Aliases IBS/CBS antigos são aceitos somente na entrada e normalizados para o schema canônico `NfseIbscbs`:\n  `ibscbs.property.cib`, `ibscbs.property.codigoCIB`, `state_region`, `estadoProvinciaRegiao`, `postal_address_code`, `foreign_postal_code`, `taxation.deferment`, `taxation.tax_situation_code`, `taxation.classification_code`, `national_dfe`, `fiscal_document` e `document`.\n\n## Nacional, municipal e IBS/CBS\n- No fluxo municipal, a API escolhe o provedor fiscal pela configuração NFS-e salva na empresa emissora.\n- No Ambiente Nacional, a API serializa os campos nacionais informados e deixa obrigatoriedade, formato e combinações fiscais para a rejeição oficial do webservice nacional.\n- Em provedores municipais aderentes ao IBS/CBS, a API envia os campos fiscais recebidos quando o layout do provedor os suporta. Campos ausentes ou inválidos devem voltar como rejeição oficial da prefeitura/provedor.\n\n## Substituição\n- Para substituir uma NFS-e autorizada, envie `substituted_reference` com `nfse_id` ou `external_id`.\n- Quando usar `substituted_reference.external_id`, o `issuer.tax_id` do próprio payload define a empresa da busca.\n- A nota original fica autorizada em estado transitório até a conclusão. Se a substituta autorizar, a original passa para `substituted`; se falhar ou for rejeitada, a original volta ao estado anterior.\n- O `external_id` pode ser reaproveitado na substituição; a unicidade é aplicada ao documento atual.\n\n## Sandbox\nUse `https://sandbox.api.edocs.ixcsoft.com.br` para testar sem emissão fiscal real. Nenhuma requisição é enviada à prefeitura ou ao Ambiente Nacional; a plataforma simula autorização e gera XML/DANFSe de teste. `environment` continua aceitando apenas `production` ou `homologation`, e cenários de rejeição, timeout ou pendência não são controlados por valores fiscais do payload.","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNfsesRequest"}}}},"responses":{"200":{"description":"NFS-e processada com sucesso quando a requisição inclui reenvio/upsert ou mistura criação e atualização.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNfsesResponse"}}}},"201":{"description":"NFS-e criada(s) com sucesso quando todos os documentos da requisição são novos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNfsesResponse"}}}},"400":{"description":"Erro de validação ou regra de negócio","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Recurso não encontrado ou emissor não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflito de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Regra de negócio não processável","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar NFS-e por CNPJ e external\_id

> Retorna a NFS-e vigente (\`is\_current: true\`) a partir do CNPJ do emitente e do \`external\_id\` atribuído pelo integrador.\
> \
> Útil quando o integrador não armazena o \`\_id\` interno e prefere consultar pelo seu próprio identificador.\
> A resposta é idêntica à de \`GET /nfse/{nfse\_id}\`, incluindo \`xml\_url\`, \`danfse\_url\`, o alias permanente \`pdf\_url\` e metadados operacionais.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"NfseReadResponse":{"type":"object","additionalProperties":false,"description":"Dados completos da NFS-e, incluindo emitente, tomador, serviço, valores, tributos e URLs de download.\nOs campos `xml_url`, `danfse_url` e o alias de compatibilidade `pdf_url` são preenchidos somente quando os artefatos existem.","properties":{"id":{"type":"string","description":"Identificador interno da NFS-e."},"workspace_id":{"type":"string"},"company_id":{"type":"string"},"external_id":{"type":"string"},"status":{"type":"string","enum":["created","processing","authorized","rejected","canceled","substituted","error","unsynced"]},"operation_status":{"type":["string","null"],"description":"Situação operacional. null = nenhuma operação em andamento; `cancellation_error` indica falha terminal de cancelamento com nova tentativa permitida quando `operation_control.can_cancel=true`, inclusive em registros legados `unsynced`.","enum":[null,"sync_pending","cancellation_pending","cancellation_error","substitution_pending"]},"operation_control":{"$ref":"#/components/schemas/NfseOperationControl"},"is_current":{"type":"boolean"},"protocol":{"type":["string","null"]},"nfse_number":{"type":["string","null"]},"authorization":{"type":["string","null"],"description":"Código de verificação retornado pelo provider municipal. No Nacional, a chave fiscal fica em `access_key`."},"access_key":{"type":["string","null"],"description":"Chave de acesso da NFS-e (50 dígitos no padrão nacional, quando disponível no municipal)."},"link":{"type":["string","null"],"description":"Link de verificação da NFS-e no portal do município."},"integration":{"type":"string","description":"Tipo de integração persistido na nota (`municipal` ou `national`)."},"provider":{"type":["string","null"],"description":"Slug técnico do provider municipal, quando a integração for municipal."},"environment":{"type":"string","enum":["production","homologation"]},"emission_datetime":{"type":["string","null"],"format":"date-time","description":"Data/hora de emissão fiscal persistida para a NFS-e."},"competence_date":{"type":["string","null"],"description":"Data de competência fiscal persistida para a NFS-e."},"send_email":{"type":"boolean","description":"Indica se a DANFSe/XML devem ser enviados por e-mail ao tomador."},"check_pending_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a nota entrou em estado de verificação pendente."},"next_check_at":{"type":["string","null"],"format":"date-time","description":"Próxima consulta automática planejada para reconciliação."},"sent_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que o envio foi concluído pelo provedor."},"authorized_at":{"type":["string","null"],"format":"date-time","description":"Data/hora de autorização fiscal da NFS-e."},"cancel_requested_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que o cancelamento foi solicitado."},"canceled_at":{"type":["string","null"],"format":"date-time","description":"Data/hora de cancelamento fiscal da NFS-e."},"cancel_code":{"type":["integer","null"],"description":"Código fiscal de cancelamento usado em cancelamento ou substituição."},"cancel_not_confirmed_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a API registrou cancelamento ainda não confirmado pelo provedor."},"cancel_not_confirmed_reason":{"type":["string","null"],"description":"Motivo registrado quando o cancelamento ainda não foi confirmado."},"substitution_requested_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que uma substituição foi solicitada."},"substitution_requested_nfse_id":{"type":["string","null"],"description":"Identificador da NFS-e criada para substituir este documento, quando aplicável."},"substituted_id":{"type":["string","null"],"description":"Identificador da NFS-e original substituída por este documento, quando aplicável."},"rejected_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a rejeição foi registrada."},"nfse_series":{"type":["string","null"],"description":"Série fiscal persistida para a NFS-e (espelha o RPS/DPS conforme o modelo fiscal de referência)."},"batch_number":{"type":["integer","null"],"description":"Número do lote de envio atribuído pelo dispatcher para providers que usam envio em lote."},"reference_model":{"type":["string","null"],"enum":[null,"rps","dps"],"description":"Modelo fiscal de referência usado nesta emissão, resolvido a partir do `setup_spec.reference_model` do provider efetivo."},"rps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores RPS da emissão municipal, quando aplicável.","properties":{"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]},"batch":{"type":["integer","null"]}}},"dps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores DPS da emissão nacional, quando aplicável.","properties":{"identifier":{"type":["string","null"]},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]}}},"issuer":{"type":"object","properties":{"tax_id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"simple_national":{"type":["integer","null"],"enum":[null,1,2,3],"description":"Enquadramento canônico do emitente no Simples Nacional. Este é o campo usado por providers ABRASF para decidir `OptanteSimplesNacional`; não confundir com `simple_national_apportionment`.\n- `1` — Não optante pelo Simples Nacional.\n- `2` — MEI optante pelo Simples Nacional.\n- `3` — ME/EPP optante pelo Simples Nacional."},"simple_national_apportionment":{"type":["integer","null"],"enum":[null,1,2,3],"description":"Regime de apuração do Simples Nacional usado apenas por layouts que possuem `regApTribSN`, como Nacional, ISSNet, RLZ e Mega. Não substitui `simple_national` e não deve ser usado para montar `OptanteSimplesNacional`.\n- `1` — Tributos federais e municipal pelo Simples Nacional.\n- `2` — Tributos federais pelo Simples Nacional e ISSQN pela NFS-e municipal.\n- `3` — Tributos federais e municipal fora do Simples Nacional."},"special_tax_regime":{"type":["integer","null"]},"tax_incentive":{"type":["integer","null"]},"is_headquarters":{"type":["boolean","null"]},"address":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string","description":"Cidade/localidade do endereço. Campo canônico do contrato NFS-e."},"municipality":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias permanente de `city`.\nAceito na entrada HTTP e devolvido nas respostas para manter integrações existentes.\nNão é usado por providers, templates, workers ou DANFSe."},"state":{"type":"string","description":"UF brasileira ou estado/província/região estrangeira."},"postal_code":{"type":"string","description":"CEP brasileiro ou código postal exterior."},"municipality_code":{"type":"string","description":"Código IBGE do município brasileiro, usado para serialização fiscal quando aplicável."},"complement":{"type":"string"},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."}}}}},"customer":{"$ref":"#/components/schemas/NfseCustomer","description":"Tomador do serviço."},"intermediary":{"oneOf":[{"$ref":"#/components/schemas/NfseIntermediary"},{"type":"null"}],"description":"Intermediário do serviço, quando informado."},"service":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"cnae_code":{"type":["string","null"]},"national_tax_code":{"type":["string","null"],"description":"Código nacional de tributação do serviço (`cTribNac`). Campo canônico."},"operation_nature":{"type":["string","null"],"description":"Natureza da operação fiscal do serviço quando o provider municipal possuir tag própria, como `NaturezaOperacao`. Não substitui `taxes.iss_taxation`."},"lc116_code":{"type":["string","null"],"description":"Código do item da lista de serviços da LC 116/2003 usado por providers municipais em `ItemListaServico` quando o layout exigir esse campo separado do código tributário municipal."},"municipal_tax_code":{"type":["string","null"]},"incidence_municipality_code":{"type":["string","null"]},"country_code":{"type":["string","null"]},"nbs_code":{"type":["string","null"]},"taxpayer_code":{"type":["string","null"]},"technical_document_id":{"type":["string","null"]},"reference_document":{"type":["string","null"]},"purchase_order_number":{"type":["string","null"]},"additional_information":{"type":["string","null"]},"event":{"$ref":"#/components/schemas/NfseServiceEvent"},"construction":{"$ref":"#/components/schemas/NfseServiceConstruction"},"foreign_trade":{"$ref":"#/components/schemas/NfseServiceForeignTrade"}}},"taxes":{"oneOf":[{"type":"object","properties":{"iss_taxation":{"type":["string","null"]},"iss_retention_type":{"type":["string","null"]},"social_retention_type":{"type":["string","null"]},"pis_cofins_cst":{"type":["string","null"]},"result_country_code":{"type":["string","null"]},"immunity_type":{"type":["string","null"]},"suspension_type":{"type":["string","null"]},"suspension_process_number":{"type":["string","null"]},"municipal_benefit":{"$ref":"#/components/schemas/NfseMunicipalBenefit"},"estimated_tax_burden":{"$ref":"#/components/schemas/NfseEstimatedTaxBurden"}}},{"type":"null"}]},"ibscbs":{"oneOf":[{"$ref":"#/components/schemas/NfseIbscbs"},{"type":"null"}]},"values":{"$ref":"#/components/schemas/NfseValues","description":"Valores da nota fiscal, incluindo deduções detalhadas quando informadas."},"cancel_reason":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"rejection_details":{"type":["array","null"],"description":"Detalhes estruturados da rejeição fiscal persistidos na NFS-e quando o provedor informa mensagens de rejeição. Este campo pode ficar ausente ou nulo quando o documento persistido não carrega detalhe estruturado.","items":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"code":{"type":["string","null"]},"message":{"type":"string"},"correction":{"type":["string","null"]}}}},"xml_url":{"type":["string","null"],"description":"URL pública para download do XML autorizado, incluindo `download_token` na querystring."},"danfse_url":{"type":["string","null"],"description":"URL pública para download da DANFSe, incluindo `download_token` na querystring."},"pdf_url":{"type":["string","null"],"description":"**Compatibilidade.** (Compatibility) Alias permanente de `danfse_url` para integrações antigas.\nMantido indefinidamente. Em código novo, prefira `danfse_url`.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NfseOperationControl":{"type":"object","additionalProperties":false,"required":["current_operation","can_cancel","can_interrupt","interrupt_available_at","elapsed_ms"],"properties":{"current_operation":{"type":["string","null"],"description":"Operação local acompanhada pela API no momento.","enum":[null,"send","cancel","substitute","post_send_verification","document_reconciliation","cancellation_reconciliation"]},"can_cancel":{"type":"boolean","description":"Indica se a interface pode liberar a ação de cancelamento para a NFS-e, considerando status local, operação ativa e capability do provedor."},"can_interrupt":{"type":"boolean","description":"Indica se a interface pode liberar a ação de interromper operação."},"interrupt_available_at":{"type":["string","null"],"format":"date-time","description":"Instante em que a interrupção fica disponível. Para `post_send_verification`, corresponde à janela de atenção de 5 minutos."},"elapsed_ms":{"type":["integer","null"],"minimum":0,"description":"Tempo decorrido desde o início da operação acompanhada, em milissegundos."}}},"NfseCustomer":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","minLength":1,"description":"CPF ou CNPJ do tomador, somente dígitos. Para tomador estrangeiro, use `nif` ou `no_nif_reason` conforme o layout fiscal."},"municipal_registration":{"type":"string","description":"Inscrição Municipal do tomador."},"nif":{"type":"string","minLength":1,"description":"Número de identificação fiscal do tomador estrangeiro."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo da ausência de NIF do tomador estrangeiro quando o layout fiscal permitir."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física do tomador."},"legal_name":{"type":"string","description":"Razão social ou nome do tomador."},"name":{"type":"string","description":"Nome fantasia do tomador."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço completo do tomador."},"phone":{"type":"string","description":"Telefone de contato do tomador."},"email":{"type":"string","format":"email","description":"E-mail de contato do tomador."}}},"NfseAddress":{"type":"object","additionalProperties":false,"properties":{"street":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Logradouro. Não aceita símbolos especiais nem quebra de linha."},"number":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Número do endereço. Não aceita símbolos especiais nem quebra de linha."},"neighborhood":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Bairro. Não aceita símbolos especiais nem quebra de linha."},"municipality":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias permanente de `city`.\nAceito na entrada HTTP e devolvido nas respostas para manter integrações existentes.\nNão é usado por providers, templates, workers ou DANFSe."},"city":{"type":"string","description":"Cidade/localidade do endereço. Campo canônico do contrato NFS-e."},"state":{"type":"string","maxLength":2,"description":"UF brasileira ou estado/província/região estrangeira."},"postal_code":{"type":"string","minLength":1,"pattern":"^(?:\\d{8}|\\d{5}-\\d{3})$","description":"CEP brasileiro ou código postal exterior."},"complement":{"type":"string","description":"Complemento do endereço."},"municipality_code":{"type":"string","maxLength":7,"description":"Código IBGE do município brasileiro, usado para serialização fiscal quando aplicável."},"country":{"type":"string","maxLength":60,"description":"Nome do país, quando útil para exibição."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."}}},"NfseIntermediary":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física, somente dígitos."},"municipal_registration":{"type":"string","description":"Inscrição Municipal."},"legal_name":{"type":"string","description":"Razão social ou nome."},"name":{"type":"string","description":"Nome fantasia ou alias aceito."},"address":{"$ref":"#/components/schemas/NfseAddress"},"phone":{"type":"string","description":"Telefone de contato."},"email":{"type":"string","format":"email","description":"E-mail de contato."},"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município."}}},"NfseServiceEvent":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","description":"Nome do evento relacionado ao serviço."},"identifier":{"type":"string","description":"Identificador do evento."},"description":{"type":"string","description":"Descrição do evento."},"start_date":{"type":"string","format":"date","description":"Data de início do evento."},"end_date":{"type":"string","format":"date","description":"Data de encerramento do evento."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço do evento."}}},"NfseServiceConstruction":{"type":"object","additionalProperties":false,"properties":{"work_code":{"type":"string","description":"Código da obra."},"cib_code":{"type":"string","description":"Código do Cadastro Imobiliário Brasileiro."},"property_registration":{"type":"string","description":"Inscrição imobiliária da obra."},"art":{"type":"string","description":"Anotação, registro ou termo de responsabilidade técnica da obra."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço da obra."}}},"NfseServiceForeignTrade":{"type":"object","additionalProperties":false,"properties":{"provision_mode":{"type":"string","description":"Modo de prestação no comércio exterior."},"relationship_type":{"type":"string","description":"Tipo de vínculo entre prestador e tomador no exterior."},"currency_code":{"type":"string","description":"Código da moeda da operação."},"foreign_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do serviço na moeda estrangeira."},"issuer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo prestador."},"customer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo tomador."},"temporary_goods_movement":{"type":"string","description":"Indicador de movimentação temporária de bens vinculada ao serviço."},"import_declaration_number":{"type":"string","description":"Número da declaração de importação relacionada ao serviço."},"export_registration_number":{"type":"string","description":"Número do registro de exportação relacionado ao serviço."},"mdic_sharing":{"type":"string","description":"Indicador de compartilhamento com o MDIC quando exigido pelo layout fiscal."}}},"NfseDecimalValue":{"oneOf":[{"type":"number"},{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$"}],"description":"Valor decimal aceito como número JSON ou string numérica decimal."},"NfseMunicipalBenefit":{"type":"object","additionalProperties":false,"properties":{"identifier":{"type":"string","pattern":"^[0-9]{14}$","description":"Identificador do benefício fiscal municipal, com 14 dígitos quando serializado no layout nacional."},"base_reduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de redução da base de cálculo concedido pelo benefício."},"base_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Percentual de redução da base de cálculo concedido pelo benefício."}}},"NfseEstimatedTaxBurden":{"type":"object","additionalProperties":false,"properties":{"federal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos federais."},"state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos estaduais."},"municipal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos municipais."},"federal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos federais."},"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos estaduais."},"municipal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos municipais."},"simple_national_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":99.99,"description":"Alíquota aproximada dos tributos para optante do Simples Nacional."}}},"NfseIbscbs":{"type":"object","additionalProperties":false,"description":"Bloco IBS/CBS compartilhado entre o Ambiente Nacional e provedores municipais aderentes ao IBS/CBS.\n`tax_situation_code` e `classification_code` são o CST/cClassTrib principal do IBS/CBS. O grupo `taxation.regular.*` representa a tributação regular e não é duplicidade desses campos principais.\nNo `national`, envie apenas os campos declaratórios do layout nacional: `purpose`, `final_consumer`, `operation_indicator`, `operation_type`, `government_entity_type`, `destination_indicator`, `references`, `tax_situation_code`/`classification_code`, `destination`, `property`, `taxation` e `reimbursements`.\nOs campos `reduction_rate`, `incidence_location_code`, `incidence_location_name`, `values` e `totals` existem no contrato canônico para provedores municipais aderentes ao IBS/CBS, mas são rejeitados pelo provedor Nacional quando a empresa usa `integration=national`.\nNão envie `ibscbs.taxation.tax_situation_code` nem `ibscbs.taxation.classification_code`; esses aliases são aceitos somente na borda HTTP do `POST /nfse` para compatibilidade de entrada e são normalizados para os campos principais.","properties":{"purpose":{"type":"string","enum":["0"],"description":"Finalidade da NFS-e no bloco IBS/CBS. No XSD nacional atual, apenas `0` é aceito."},"final_consumer":{"type":"string","enum":["0","1"],"description":"Indicador de consumidor final no bloco IBS/CBS. Opcional no XSD nacional."},"operation_indicator":{"type":"string","pattern":"^[0-9]{6}$","description":"Código do indicador da operação no bloco IBS/CBS."},"operation_type":{"type":"string","enum":["1","2","3","4","5"],"description":"Tipo da operação no bloco IBS/CBS."},"government_entity_type":{"type":"string","enum":["1","2","3","4"],"description":"Tipo de ente governamental no bloco IBS/CBS."},"destination_indicator":{"type":"string","enum":["0","1"],"description":"Indicador do destino da operação no bloco IBS/CBS."},"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST principal aplicado ao bloco IBS/CBS. Não confundir com `taxation.regular.tax_situation_code`, que pertence ao grupo de tributação regular."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib principal usado no bloco IBS/CBS. Não confundir com `taxation.regular.classification_code`, que pertence ao grupo de tributação regular."},"reduction_rate":{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$","description":"Percentual redutor serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_code":{"type":"string","description":"Código do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_name":{"type":"string","description":"Nome do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"references":{"type":"array","description":"Referências técnicas aceitas pelo layout IBS/CBS.","items":{"type":"string"}},"destination":{"$ref":"#/components/schemas/NfseIbscbsDestination","description":"Destinatário do serviço no grupo declaratório IBS/CBS do Ambiente Nacional."},"property":{"$ref":"#/components/schemas/NfseIbscbsProperty","description":"Informações de imóvel no grupo declaratório IBS/CBS do Ambiente Nacional."},"taxation":{"$ref":"#/components/schemas/NfseIbscbsTaxation","description":"Subgrupos declaratórios de tributação IBS/CBS. Não contém o CST/cClassTrib principal; esses campos ficam em `ibscbs.tax_situation_code` e `ibscbs.classification_code`."},"reimbursements":{"type":"array","maxItems":1000,"description":"Documentos de reembolso, repasse ou ressarcimento no grupo declaratório IBS/CBS.","items":{"$ref":"#/components/schemas/NfseIbscbsReimbursement"}},"values":{"$ref":"#/components/schemas/NfseIbscbsValues","description":"Valores calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."},"totals":{"$ref":"#/components/schemas/NfseIbscbsTotals","description":"Totais calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."}}},"NfseIbscbsDestination":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome do destinatário."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress"},"phone":{"type":"string","description":"Telefone do destinatário."},"email":{"type":"string","format":"email","description":"E-mail do destinatário."}}},"NfseIbscbsAddress":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município para endereço nacional."},"postal_code":{"type":"string","description":"CEP brasileiro ou código postal exterior."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."},"municipality":{"type":"string","description":"Município/localidade do endereço no contrato canônico NFS-e."},"state":{"type":"string","description":"UF brasileira ou estado/província/região estrangeira."},"street":{"type":"string","description":"Logradouro."},"number":{"type":"string","description":"Número do endereço."},"complement":{"type":"string","description":"Complemento do endereço."},"neighborhood":{"type":"string","description":"Bairro."}}},"NfseIbscbsProperty":{"type":"object","additionalProperties":false,"properties":{"registration_code":{"type":"string","description":"Inscrição imobiliária fiscal."},"cib_code":{"type":"string","minLength":8,"maxLength":8,"description":"Código do Cadastro Imobiliário Brasileiro."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress","description":"Endereço do imóvel. No Nacional, informe `cib_code` ou `address`, nunca ambos."}}},"NfseIbscbsTaxation":{"type":"object","additionalProperties":false,"description":"Subgrupos declaratórios de tributação IBS/CBS. `regular` é tributação regular distinta dos campos principais do bloco.","properties":{"credit_presumed_code":{"type":"string","pattern":"^[0-9]{2}$","description":"Código de crédito presumido IBS/CBS."},"regular":{"$ref":"#/components/schemas/NfseIbscbsRegularTaxation","description":"Tributação regular IBS/CBS, distinta do CST/cClassTrib principal do bloco."},"deferral":{"$ref":"#/components/schemas/NfseIbscbsDeferral"}}},"NfseIbscbsRegularTaxation":{"type":"object","additionalProperties":false,"properties":{"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST da tributação regular. Campo distinto de `ibscbs.tax_situation_code`."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib da tributação regular. Campo distinto de `ibscbs.classification_code`."}}},"NfseIbscbsDeferral":{"type":"object","additionalProperties":false,"properties":{"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS estadual."},"municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS municipal."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento da CBS."}}},"NfseIbscbsReimbursement":{"type":"object","additionalProperties":false,"properties":{"dfe_national":{"$ref":"#/components/schemas/NfseIbscbsDfeNational"},"other_fiscal_document":{"$ref":"#/components/schemas/NfseIbscbsOtherFiscalDocument"},"other_document":{"$ref":"#/components/schemas/NfseIbscbsOtherDocument"},"supplier":{"$ref":"#/components/schemas/NfseIbscbsIdentity"},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento referenciado."},"competence_date":{"type":"string","format":"date","description":"Data de competência do documento referenciado."},"type":{"type":"string","enum":["01","02","03","04","99"],"description":"Tipo de reembolso, repasse ou ressarcimento."},"type_description":{"type":"string","description":"Descrição quando `type` for `99`."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do reembolso, repasse ou ressarcimento."}}},"NfseIbscbsDfeNational":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","9"],"description":"Tipo de chave do documento fiscal eletrônico nacional."},"type_description":{"type":"string","description":"Descrição quando `type` for `9`."},"key":{"type":"string","maxLength":50,"description":"Chave do documento fiscal eletrônico."}}},"NfseIbscbsOtherFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código do município emissor do documento fiscal."},"number":{"type":"string","description":"Número do documento fiscal."},"description":{"type":"string","description":"Descrição do documento fiscal."}}},"NfseIbscbsOtherDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento não fiscal."},"description":{"type":"string","description":"Descrição do documento não fiscal."}}},"NfseIbscbsIdentity":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome."}}},"NfseIbscbsValues":{"type":"object","additionalProperties":false,"description":"Valores calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo do IBS/CBS."},"state":{"$ref":"#/components/schemas/NfseIbscbsStateValues"},"municipality":{"$ref":"#/components/schemas/NfseIbscbsMunicipalityValues"},"federal":{"$ref":"#/components/schemas/NfseIbscbsFederalValues"}}},"NfseIbscbsStateValues":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota estadual do IBS."},"ibs_state_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota estadual do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_state_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva estadual do IBS."}}},"NfseIbscbsMunicipalityValues":{"type":"object","additionalProperties":false,"properties":{"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota municipal do IBS."},"ibs_municipality_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota municipal do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_municipality_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva municipal do IBS."}}},"NfseIbscbsFederalValues":{"type":"object","additionalProperties":false,"properties":{"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota federal da CBS."},"cbs_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota federal da CBS em providers municipais aderentes ao IBS/CBS."},"cbs_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva federal da CBS."}}},"NfseIbscbsTotals":{"type":"object","additionalProperties":false,"description":"Totais calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"total_nf_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total da NFS-e usado no bloco IBS/CBS."},"ibs":{"$ref":"#/components/schemas/NfseIbscbsIbsTotals"},"cbs":{"$ref":"#/components/schemas/NfseIbscbsCbsTotals"},"government_purchase":{"$ref":"#/components/schemas/NfseIbscbsGovernmentPurchaseTotals"}}},"NfseIbscbsIbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado do IBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"state_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"},"municipality_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"}}},"NfseIbscbsCreditPresumedTotals":{"type":"object","additionalProperties":false,"properties":{"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de crédito presumido em providers municipais aderentes ao IBS/CBS."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de crédito presumido em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsIbsLocationTotal":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total consolidado do grupo correspondente."},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido do grupo correspondente em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsCbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado da CBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido da CBS em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsGovernmentPurchaseTotals":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota estadual do IBS em compra governamental."},"ibs_state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor estadual do IBS em compra governamental."},"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota municipal do IBS em compra governamental."},"ibs_municipality_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor municipal do IBS em compra governamental."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da CBS em compra governamental."},"cbs_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CBS em compra governamental."}}},"NfseValues":{"type":"object","additionalProperties":false,"required":["total_amount"],"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total do serviço."},"net_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor líquido do serviço."},"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota do ISS."},"iss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do ISS."},"unconditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto incondicional aplicado ao serviço."},"conditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto condicional aplicado ao serviço."},"ir_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do IR retido na fonte."},"pis_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do PIS retido na fonte."},"cofins_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da COFINS retida na fonte."},"inss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do INSS retido na fonte."},"csll_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CSLL retida na fonte."},"other_retentions":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Outras retenções aplicadas ao serviço."},"deductions_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total das deduções."},"intermediary_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor recebido pelo intermediário do serviço, quando o layout fiscal exigir esse destaque."},"cp_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de Contribuição Previdenciária retido."},"pis_cofins_base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo compartilhada para PIS e COFINS (vBCPisCofins no XML)."},"pis_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota do PIS (pAliqPis no XML)."},"cofins_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da COFINS (pAliqCofins no XML)."},"deductions":{"type":"array","maxItems":1000,"description":"Documentos fiscais usados para dedução ou redução da base de cálculo, quando o layout fiscal permitir.","items":{"$ref":"#/components/schemas/NfseDeduction"}}}},"NfseDeduction":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","4","5","6","7","8","9","99"],"description":"Tipo fiscal da dedução conforme o layout aplicável."},"description":{"type":"string","maxLength":150,"description":"Descrição da dedução ou redução."},"deductible_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do documento elegível à dedução."},"deduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor efetivamente deduzido."},"document_kind":{"type":"string","description":"Tipo de documento que comprova a dedução."},"nfse_key":{"type":"string","pattern":"^[0-9]{50}$","description":"Chave de acesso da NFS-e usada como documento de dedução, com 50 dígitos quando exigida pelo Nacional."},"nfe_key":{"type":"string","pattern":"^[0-9]{44}$","description":"Chave de acesso da NF-e usada como documento de dedução, com 44 dígitos quando exigida pelo Nacional."},"other_document_number":{"type":"string","maxLength":255,"description":"Número de outro documento aceito para dedução."},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento de dedução."},"municipal_nfse":{"$ref":"#/components/schemas/NfseDeductionMunicipalNfse"},"fiscal_document":{"$ref":"#/components/schemas/NfseDeductionFiscalDocument"},"supplier":{"$ref":"#/components/schemas/NfseIntermediary","description":"Fornecedor ou prestador associado ao documento de dedução."}}},"NfseDeductionMunicipalNfse":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município da NFS-e dedutível."},"number":{"type":"string","description":"Número da NFS-e dedutível."},"verification_code":{"type":"string","pattern":"^[a-zA-Z0-9]{1,9}$","description":"Código de verificação da NFS-e dedutível."}}},"NfseDeductionFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento fiscal dedutível."},"model":{"type":"string","description":"Modelo do documento fiscal dedutível."},"series":{"type":"string","description":"Série do documento fiscal dedutível."},"state":{"type":"string","maxLength":2,"description":"UF do documento fiscal dedutível."},"access_key":{"type":"string","description":"Chave de acesso do documento fiscal dedutível."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/{issuer_tax_id}/{external_id}":{"get":{"operationId":"getNfseByExternalId","tags":["NFS-e"],"summary":"Consultar NFS-e por CNPJ e external_id","description":"Retorna a NFS-e vigente (`is_current: true`) a partir do CNPJ do emitente e do `external_id` atribuído pelo integrador.\n\nÚtil quando o integrador não armazena o `_id` interno e prefere consultar pelo seu próprio identificador.\nA resposta é idêntica à de `GET /nfse/{nfse_id}`, incluindo `xml_url`, `danfse_url`, o alias permanente `pdf_url` e metadados operacionais.","parameters":[{"name":"issuer_tax_id","in":"path","required":true,"description":"CNPJ do emitente (somente dígitos, 14 caracteres).","schema":{"type":"string","pattern":"^\\d{14}$"}},{"name":"external_id","in":"path","required":true,"description":"Identificador externo atribuído pelo integrador na emissão.","schema":{"type":"string"}},{"$ref":"#/components/parameters/AcceptLanguage"}],"responses":{"200":{"description":"NFS-e encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseReadResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar NFS-e por ID

> Retorna os dados completos de uma NFS-e, incluindo URLs de download do XML e da DANFSe quando disponíveis.\
> \
> Campos adicionais na resposta:\
> \- \`xml\_url\`: URL pública para download do XML autorizado (quando disponível).\
> \- \`danfse\_url\`: URL pública para download da DANFSe em PDF (quando disponível).\
> \- \`pdf\_url\`: \*\*Compatibilidade.\*\* (Compatibility) Alias permanente de \`danfse\_url\` para integrações antigas. Mantido indefinidamente.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"schemas":{"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"NfseReadResponse":{"type":"object","additionalProperties":false,"description":"Dados completos da NFS-e, incluindo emitente, tomador, serviço, valores, tributos e URLs de download.\nOs campos `xml_url`, `danfse_url` e o alias de compatibilidade `pdf_url` são preenchidos somente quando os artefatos existem.","properties":{"id":{"type":"string","description":"Identificador interno da NFS-e."},"workspace_id":{"type":"string"},"company_id":{"type":"string"},"external_id":{"type":"string"},"status":{"type":"string","enum":["created","processing","authorized","rejected","canceled","substituted","error","unsynced"]},"operation_status":{"type":["string","null"],"description":"Situação operacional. null = nenhuma operação em andamento; `cancellation_error` indica falha terminal de cancelamento com nova tentativa permitida quando `operation_control.can_cancel=true`, inclusive em registros legados `unsynced`.","enum":[null,"sync_pending","cancellation_pending","cancellation_error","substitution_pending"]},"operation_control":{"$ref":"#/components/schemas/NfseOperationControl"},"is_current":{"type":"boolean"},"protocol":{"type":["string","null"]},"nfse_number":{"type":["string","null"]},"authorization":{"type":["string","null"],"description":"Código de verificação retornado pelo provider municipal. No Nacional, a chave fiscal fica em `access_key`."},"access_key":{"type":["string","null"],"description":"Chave de acesso da NFS-e (50 dígitos no padrão nacional, quando disponível no municipal)."},"link":{"type":["string","null"],"description":"Link de verificação da NFS-e no portal do município."},"integration":{"type":"string","description":"Tipo de integração persistido na nota (`municipal` ou `national`)."},"provider":{"type":["string","null"],"description":"Slug técnico do provider municipal, quando a integração for municipal."},"environment":{"type":"string","enum":["production","homologation"]},"emission_datetime":{"type":["string","null"],"format":"date-time","description":"Data/hora de emissão fiscal persistida para a NFS-e."},"competence_date":{"type":["string","null"],"description":"Data de competência fiscal persistida para a NFS-e."},"send_email":{"type":"boolean","description":"Indica se a DANFSe/XML devem ser enviados por e-mail ao tomador."},"check_pending_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a nota entrou em estado de verificação pendente."},"next_check_at":{"type":["string","null"],"format":"date-time","description":"Próxima consulta automática planejada para reconciliação."},"sent_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que o envio foi concluído pelo provedor."},"authorized_at":{"type":["string","null"],"format":"date-time","description":"Data/hora de autorização fiscal da NFS-e."},"cancel_requested_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que o cancelamento foi solicitado."},"canceled_at":{"type":["string","null"],"format":"date-time","description":"Data/hora de cancelamento fiscal da NFS-e."},"cancel_code":{"type":["integer","null"],"description":"Código fiscal de cancelamento usado em cancelamento ou substituição."},"cancel_not_confirmed_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a API registrou cancelamento ainda não confirmado pelo provedor."},"cancel_not_confirmed_reason":{"type":["string","null"],"description":"Motivo registrado quando o cancelamento ainda não foi confirmado."},"substitution_requested_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que uma substituição foi solicitada."},"substitution_requested_nfse_id":{"type":["string","null"],"description":"Identificador da NFS-e criada para substituir este documento, quando aplicável."},"substituted_id":{"type":["string","null"],"description":"Identificador da NFS-e original substituída por este documento, quando aplicável."},"rejected_at":{"type":["string","null"],"format":"date-time","description":"Data/hora em que a rejeição foi registrada."},"nfse_series":{"type":["string","null"],"description":"Série fiscal persistida para a NFS-e (espelha o RPS/DPS conforme o modelo fiscal de referência)."},"batch_number":{"type":["integer","null"],"description":"Número do lote de envio atribuído pelo dispatcher para providers que usam envio em lote."},"reference_model":{"type":["string","null"],"enum":[null,"rps","dps"],"description":"Modelo fiscal de referência usado nesta emissão, resolvido a partir do `setup_spec.reference_model` do provider efetivo."},"rps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores RPS da emissão municipal, quando aplicável.","properties":{"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]},"batch":{"type":["integer","null"]}}},"dps":{"type":["object","null"],"additionalProperties":false,"description":"Identificadores DPS da emissão nacional, quando aplicável.","properties":{"identifier":{"type":["string","null"]},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"type":{"type":["string","null"]}}},"issuer":{"type":"object","properties":{"tax_id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"simple_national":{"type":["integer","null"],"enum":[null,1,2,3],"description":"Enquadramento canônico do emitente no Simples Nacional. Este é o campo usado por providers ABRASF para decidir `OptanteSimplesNacional`; não confundir com `simple_national_apportionment`.\n- `1` — Não optante pelo Simples Nacional.\n- `2` — MEI optante pelo Simples Nacional.\n- `3` — ME/EPP optante pelo Simples Nacional."},"simple_national_apportionment":{"type":["integer","null"],"enum":[null,1,2,3],"description":"Regime de apuração do Simples Nacional usado apenas por layouts que possuem `regApTribSN`, como Nacional, ISSNet, RLZ e Mega. Não substitui `simple_national` e não deve ser usado para montar `OptanteSimplesNacional`.\n- `1` — Tributos federais e municipal pelo Simples Nacional.\n- `2` — Tributos federais pelo Simples Nacional e ISSQN pela NFS-e municipal.\n- `3` — Tributos federais e municipal fora do Simples Nacional."},"special_tax_regime":{"type":["integer","null"]},"tax_incentive":{"type":["integer","null"]},"is_headquarters":{"type":["boolean","null"]},"address":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string","description":"Cidade/localidade do endereço. Campo canônico do contrato NFS-e."},"municipality":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias permanente de `city`.\nAceito na entrada HTTP e devolvido nas respostas para manter integrações existentes.\nNão é usado por providers, templates, workers ou DANFSe."},"state":{"type":"string","description":"UF brasileira ou estado/província/região estrangeira."},"postal_code":{"type":"string","description":"CEP brasileiro ou código postal exterior."},"municipality_code":{"type":"string","description":"Código IBGE do município brasileiro, usado para serialização fiscal quando aplicável."},"complement":{"type":"string"},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."}}}}},"customer":{"$ref":"#/components/schemas/NfseCustomer","description":"Tomador do serviço."},"intermediary":{"oneOf":[{"$ref":"#/components/schemas/NfseIntermediary"},{"type":"null"}],"description":"Intermediário do serviço, quando informado."},"service":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"cnae_code":{"type":["string","null"]},"national_tax_code":{"type":["string","null"],"description":"Código nacional de tributação do serviço (`cTribNac`). Campo canônico."},"operation_nature":{"type":["string","null"],"description":"Natureza da operação fiscal do serviço quando o provider municipal possuir tag própria, como `NaturezaOperacao`. Não substitui `taxes.iss_taxation`."},"lc116_code":{"type":["string","null"],"description":"Código do item da lista de serviços da LC 116/2003 usado por providers municipais em `ItemListaServico` quando o layout exigir esse campo separado do código tributário municipal."},"municipal_tax_code":{"type":["string","null"]},"incidence_municipality_code":{"type":["string","null"]},"country_code":{"type":["string","null"]},"nbs_code":{"type":["string","null"]},"taxpayer_code":{"type":["string","null"]},"technical_document_id":{"type":["string","null"]},"reference_document":{"type":["string","null"]},"purchase_order_number":{"type":["string","null"]},"additional_information":{"type":["string","null"]},"event":{"$ref":"#/components/schemas/NfseServiceEvent"},"construction":{"$ref":"#/components/schemas/NfseServiceConstruction"},"foreign_trade":{"$ref":"#/components/schemas/NfseServiceForeignTrade"}}},"taxes":{"oneOf":[{"type":"object","properties":{"iss_taxation":{"type":["string","null"]},"iss_retention_type":{"type":["string","null"]},"social_retention_type":{"type":["string","null"]},"pis_cofins_cst":{"type":["string","null"]},"result_country_code":{"type":["string","null"]},"immunity_type":{"type":["string","null"]},"suspension_type":{"type":["string","null"]},"suspension_process_number":{"type":["string","null"]},"municipal_benefit":{"$ref":"#/components/schemas/NfseMunicipalBenefit"},"estimated_tax_burden":{"$ref":"#/components/schemas/NfseEstimatedTaxBurden"}}},{"type":"null"}]},"ibscbs":{"oneOf":[{"$ref":"#/components/schemas/NfseIbscbs"},{"type":"null"}]},"values":{"$ref":"#/components/schemas/NfseValues","description":"Valores da nota fiscal, incluindo deduções detalhadas quando informadas."},"cancel_reason":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"rejection_details":{"type":["array","null"],"description":"Detalhes estruturados da rejeição fiscal persistidos na NFS-e quando o provedor informa mensagens de rejeição. Este campo pode ficar ausente ou nulo quando o documento persistido não carrega detalhe estruturado.","items":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"code":{"type":["string","null"]},"message":{"type":"string"},"correction":{"type":["string","null"]}}}},"xml_url":{"type":["string","null"],"description":"URL pública para download do XML autorizado, incluindo `download_token` na querystring."},"danfse_url":{"type":["string","null"],"description":"URL pública para download da DANFSe, incluindo `download_token` na querystring."},"pdf_url":{"type":["string","null"],"description":"**Compatibilidade.** (Compatibility) Alias permanente de `danfse_url` para integrações antigas.\nMantido indefinidamente. Em código novo, prefira `danfse_url`.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NfseOperationControl":{"type":"object","additionalProperties":false,"required":["current_operation","can_cancel","can_interrupt","interrupt_available_at","elapsed_ms"],"properties":{"current_operation":{"type":["string","null"],"description":"Operação local acompanhada pela API no momento.","enum":[null,"send","cancel","substitute","post_send_verification","document_reconciliation","cancellation_reconciliation"]},"can_cancel":{"type":"boolean","description":"Indica se a interface pode liberar a ação de cancelamento para a NFS-e, considerando status local, operação ativa e capability do provedor."},"can_interrupt":{"type":"boolean","description":"Indica se a interface pode liberar a ação de interromper operação."},"interrupt_available_at":{"type":["string","null"],"format":"date-time","description":"Instante em que a interrupção fica disponível. Para `post_send_verification`, corresponde à janela de atenção de 5 minutos."},"elapsed_ms":{"type":["integer","null"],"minimum":0,"description":"Tempo decorrido desde o início da operação acompanhada, em milissegundos."}}},"NfseCustomer":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","minLength":1,"description":"CPF ou CNPJ do tomador, somente dígitos. Para tomador estrangeiro, use `nif` ou `no_nif_reason` conforme o layout fiscal."},"municipal_registration":{"type":"string","description":"Inscrição Municipal do tomador."},"nif":{"type":"string","minLength":1,"description":"Número de identificação fiscal do tomador estrangeiro."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo da ausência de NIF do tomador estrangeiro quando o layout fiscal permitir."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física do tomador."},"legal_name":{"type":"string","description":"Razão social ou nome do tomador."},"name":{"type":"string","description":"Nome fantasia do tomador."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço completo do tomador."},"phone":{"type":"string","description":"Telefone de contato do tomador."},"email":{"type":"string","format":"email","description":"E-mail de contato do tomador."}}},"NfseAddress":{"type":"object","additionalProperties":false,"properties":{"street":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Logradouro. Não aceita símbolos especiais nem quebra de linha."},"number":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Número do endereço. Não aceita símbolos especiais nem quebra de linha."},"neighborhood":{"type":"string","minLength":1,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ0-9 .,-]+$","description":"Bairro. Não aceita símbolos especiais nem quebra de linha."},"municipality":{"type":"string","description":"**Compatibilidade.** (Compatibility) Alias permanente de `city`.\nAceito na entrada HTTP e devolvido nas respostas para manter integrações existentes.\nNão é usado por providers, templates, workers ou DANFSe."},"city":{"type":"string","description":"Cidade/localidade do endereço. Campo canônico do contrato NFS-e."},"state":{"type":"string","maxLength":2,"description":"UF brasileira ou estado/província/região estrangeira."},"postal_code":{"type":"string","minLength":1,"pattern":"^(?:\\d{8}|\\d{5}-\\d{3})$","description":"CEP brasileiro ou código postal exterior."},"complement":{"type":"string","description":"Complemento do endereço."},"municipality_code":{"type":"string","maxLength":7,"description":"Código IBGE do município brasileiro, usado para serialização fiscal quando aplicável."},"country":{"type":"string","maxLength":60,"description":"Nome do país, quando útil para exibição."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."}}},"NfseIntermediary":{"type":"object","additionalProperties":false,"required":["legal_name"],"anyOf":[{"required":["tax_id"]},{"required":["nif"]},{"required":["no_nif_reason"]}],"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"caepf":{"type":"string","description":"Cadastro de Atividade Econômica da Pessoa Física, somente dígitos."},"municipal_registration":{"type":"string","description":"Inscrição Municipal."},"legal_name":{"type":"string","description":"Razão social ou nome."},"name":{"type":"string","description":"Nome fantasia ou alias aceito."},"address":{"$ref":"#/components/schemas/NfseAddress"},"phone":{"type":"string","description":"Telefone de contato."},"email":{"type":"string","format":"email","description":"E-mail de contato."},"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município."}}},"NfseServiceEvent":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","description":"Nome do evento relacionado ao serviço."},"identifier":{"type":"string","description":"Identificador do evento."},"description":{"type":"string","description":"Descrição do evento."},"start_date":{"type":"string","format":"date","description":"Data de início do evento."},"end_date":{"type":"string","format":"date","description":"Data de encerramento do evento."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço do evento."}}},"NfseServiceConstruction":{"type":"object","additionalProperties":false,"properties":{"work_code":{"type":"string","description":"Código da obra."},"cib_code":{"type":"string","description":"Código do Cadastro Imobiliário Brasileiro."},"property_registration":{"type":"string","description":"Inscrição imobiliária da obra."},"art":{"type":"string","description":"Anotação, registro ou termo de responsabilidade técnica da obra."},"address":{"$ref":"#/components/schemas/NfseAddress","description":"Endereço da obra."}}},"NfseServiceForeignTrade":{"type":"object","additionalProperties":false,"properties":{"provision_mode":{"type":"string","description":"Modo de prestação no comércio exterior."},"relationship_type":{"type":"string","description":"Tipo de vínculo entre prestador e tomador no exterior."},"currency_code":{"type":"string","description":"Código da moeda da operação."},"foreign_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do serviço na moeda estrangeira."},"issuer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo prestador."},"customer_support_mechanism":{"type":"string","description":"Mecanismo de apoio ou fomento usado pelo tomador."},"temporary_goods_movement":{"type":"string","description":"Indicador de movimentação temporária de bens vinculada ao serviço."},"import_declaration_number":{"type":"string","description":"Número da declaração de importação relacionada ao serviço."},"export_registration_number":{"type":"string","description":"Número do registro de exportação relacionado ao serviço."},"mdic_sharing":{"type":"string","description":"Indicador de compartilhamento com o MDIC quando exigido pelo layout fiscal."}}},"NfseDecimalValue":{"oneOf":[{"type":"number"},{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$"}],"description":"Valor decimal aceito como número JSON ou string numérica decimal."},"NfseMunicipalBenefit":{"type":"object","additionalProperties":false,"properties":{"identifier":{"type":"string","pattern":"^[0-9]{14}$","description":"Identificador do benefício fiscal municipal, com 14 dígitos quando serializado no layout nacional."},"base_reduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de redução da base de cálculo concedido pelo benefício."},"base_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Percentual de redução da base de cálculo concedido pelo benefício."}}},"NfseEstimatedTaxBurden":{"type":"object","additionalProperties":false,"properties":{"federal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos federais."},"state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos estaduais."},"municipal_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999999999.99,"multipleOf":0.01,"description":"Valor aproximado de tributos municipais."},"federal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos federais."},"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos estaduais."},"municipal_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":999.99,"description":"Alíquota aproximada de tributos municipais."},"simple_national_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":99.99,"description":"Alíquota aproximada dos tributos para optante do Simples Nacional."}}},"NfseIbscbs":{"type":"object","additionalProperties":false,"description":"Bloco IBS/CBS compartilhado entre o Ambiente Nacional e provedores municipais aderentes ao IBS/CBS.\n`tax_situation_code` e `classification_code` são o CST/cClassTrib principal do IBS/CBS. O grupo `taxation.regular.*` representa a tributação regular e não é duplicidade desses campos principais.\nNo `national`, envie apenas os campos declaratórios do layout nacional: `purpose`, `final_consumer`, `operation_indicator`, `operation_type`, `government_entity_type`, `destination_indicator`, `references`, `tax_situation_code`/`classification_code`, `destination`, `property`, `taxation` e `reimbursements`.\nOs campos `reduction_rate`, `incidence_location_code`, `incidence_location_name`, `values` e `totals` existem no contrato canônico para provedores municipais aderentes ao IBS/CBS, mas são rejeitados pelo provedor Nacional quando a empresa usa `integration=national`.\nNão envie `ibscbs.taxation.tax_situation_code` nem `ibscbs.taxation.classification_code`; esses aliases são aceitos somente na borda HTTP do `POST /nfse` para compatibilidade de entrada e são normalizados para os campos principais.","properties":{"purpose":{"type":"string","enum":["0"],"description":"Finalidade da NFS-e no bloco IBS/CBS. No XSD nacional atual, apenas `0` é aceito."},"final_consumer":{"type":"string","enum":["0","1"],"description":"Indicador de consumidor final no bloco IBS/CBS. Opcional no XSD nacional."},"operation_indicator":{"type":"string","pattern":"^[0-9]{6}$","description":"Código do indicador da operação no bloco IBS/CBS."},"operation_type":{"type":"string","enum":["1","2","3","4","5"],"description":"Tipo da operação no bloco IBS/CBS."},"government_entity_type":{"type":"string","enum":["1","2","3","4"],"description":"Tipo de ente governamental no bloco IBS/CBS."},"destination_indicator":{"type":"string","enum":["0","1"],"description":"Indicador do destino da operação no bloco IBS/CBS."},"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST principal aplicado ao bloco IBS/CBS. Não confundir com `taxation.regular.tax_situation_code`, que pertence ao grupo de tributação regular."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib principal usado no bloco IBS/CBS. Não confundir com `taxation.regular.classification_code`, que pertence ao grupo de tributação regular."},"reduction_rate":{"type":"string","pattern":"^\\\\d+(?:\\\\.\\\\d+)?$","description":"Percentual redutor serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_code":{"type":"string","description":"Código do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"incidence_location_name":{"type":"string","description":"Nome do local de incidência do IBS/CBS serializado por providers municipais cujo template consome esse campo. Rejeição fiscal pertence ao provedor."},"references":{"type":"array","description":"Referências técnicas aceitas pelo layout IBS/CBS.","items":{"type":"string"}},"destination":{"$ref":"#/components/schemas/NfseIbscbsDestination","description":"Destinatário do serviço no grupo declaratório IBS/CBS do Ambiente Nacional."},"property":{"$ref":"#/components/schemas/NfseIbscbsProperty","description":"Informações de imóvel no grupo declaratório IBS/CBS do Ambiente Nacional."},"taxation":{"$ref":"#/components/schemas/NfseIbscbsTaxation","description":"Subgrupos declaratórios de tributação IBS/CBS. Não contém o CST/cClassTrib principal; esses campos ficam em `ibscbs.tax_situation_code` e `ibscbs.classification_code`."},"reimbursements":{"type":"array","maxItems":1000,"description":"Documentos de reembolso, repasse ou ressarcimento no grupo declaratório IBS/CBS.","items":{"$ref":"#/components/schemas/NfseIbscbsReimbursement"}},"values":{"$ref":"#/components/schemas/NfseIbscbsValues","description":"Valores calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."},"totals":{"$ref":"#/components/schemas/NfseIbscbsTotals","description":"Totais calculados do IBS/CBS serializados por providers municipais cujo template consome esse grupo. Rejeição fiscal pertence ao provedor."}}},"NfseIbscbsDestination":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome do destinatário."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress"},"phone":{"type":"string","description":"Telefone do destinatário."},"email":{"type":"string","format":"email","description":"E-mail do destinatário."}}},"NfseIbscbsAddress":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município para endereço nacional."},"postal_code":{"type":"string","description":"CEP brasileiro ou código postal exterior."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"Código ISO 3166-1 alfa-2 do país."},"municipality":{"type":"string","description":"Município/localidade do endereço no contrato canônico NFS-e."},"state":{"type":"string","description":"UF brasileira ou estado/província/região estrangeira."},"street":{"type":"string","description":"Logradouro."},"number":{"type":"string","description":"Número do endereço."},"complement":{"type":"string","description":"Complemento do endereço."},"neighborhood":{"type":"string","description":"Bairro."}}},"NfseIbscbsProperty":{"type":"object","additionalProperties":false,"properties":{"registration_code":{"type":"string","description":"Inscrição imobiliária fiscal."},"cib_code":{"type":"string","minLength":8,"maxLength":8,"description":"Código do Cadastro Imobiliário Brasileiro."},"address":{"$ref":"#/components/schemas/NfseIbscbsAddress","description":"Endereço do imóvel. No Nacional, informe `cib_code` ou `address`, nunca ambos."}}},"NfseIbscbsTaxation":{"type":"object","additionalProperties":false,"description":"Subgrupos declaratórios de tributação IBS/CBS. `regular` é tributação regular distinta dos campos principais do bloco.","properties":{"credit_presumed_code":{"type":"string","pattern":"^[0-9]{2}$","description":"Código de crédito presumido IBS/CBS."},"regular":{"$ref":"#/components/schemas/NfseIbscbsRegularTaxation","description":"Tributação regular IBS/CBS, distinta do CST/cClassTrib principal do bloco."},"deferral":{"$ref":"#/components/schemas/NfseIbscbsDeferral"}}},"NfseIbscbsRegularTaxation":{"type":"object","additionalProperties":false,"properties":{"tax_situation_code":{"type":"string","pattern":"^[0-9]{3}$","description":"CST da tributação regular. Campo distinto de `ibscbs.tax_situation_code`."},"classification_code":{"type":"string","pattern":"^[0-9]{6}$","description":"cClassTrib da tributação regular. Campo distinto de `ibscbs.classification_code`."}}},"NfseIbscbsDeferral":{"type":"object","additionalProperties":false,"properties":{"state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS estadual."},"municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento do IBS municipal."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de diferimento da CBS."}}},"NfseIbscbsReimbursement":{"type":"object","additionalProperties":false,"properties":{"dfe_national":{"$ref":"#/components/schemas/NfseIbscbsDfeNational"},"other_fiscal_document":{"$ref":"#/components/schemas/NfseIbscbsOtherFiscalDocument"},"other_document":{"$ref":"#/components/schemas/NfseIbscbsOtherDocument"},"supplier":{"$ref":"#/components/schemas/NfseIbscbsIdentity"},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento referenciado."},"competence_date":{"type":"string","format":"date","description":"Data de competência do documento referenciado."},"type":{"type":"string","enum":["01","02","03","04","99"],"description":"Tipo de reembolso, repasse ou ressarcimento."},"type_description":{"type":"string","description":"Descrição quando `type` for `99`."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do reembolso, repasse ou ressarcimento."}}},"NfseIbscbsDfeNational":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","9"],"description":"Tipo de chave do documento fiscal eletrônico nacional."},"type_description":{"type":"string","description":"Descrição quando `type` for `9`."},"key":{"type":"string","maxLength":50,"description":"Chave do documento fiscal eletrônico."}}},"NfseIbscbsOtherFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código do município emissor do documento fiscal."},"number":{"type":"string","description":"Número do documento fiscal."},"description":{"type":"string","description":"Descrição do documento fiscal."}}},"NfseIbscbsOtherDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento não fiscal."},"description":{"type":"string","description":"Descrição do documento não fiscal."}}},"NfseIbscbsIdentity":{"type":"object","additionalProperties":false,"properties":{"tax_id":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nif":{"type":"string","description":"Número de identificação fiscal no exterior."},"no_nif_reason":{"type":"string","enum":["0","1","2"],"description":"Motivo para ausência de NIF."},"legal_name":{"type":"string","description":"Razão social ou nome."}}},"NfseIbscbsValues":{"type":"object","additionalProperties":false,"description":"Valores calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo do IBS/CBS."},"state":{"$ref":"#/components/schemas/NfseIbscbsStateValues"},"municipality":{"$ref":"#/components/schemas/NfseIbscbsMunicipalityValues"},"federal":{"$ref":"#/components/schemas/NfseIbscbsFederalValues"}}},"NfseIbscbsStateValues":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota estadual do IBS."},"ibs_state_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota estadual do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_state_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva estadual do IBS."}}},"NfseIbscbsMunicipalityValues":{"type":"object","additionalProperties":false,"properties":{"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota municipal do IBS."},"ibs_municipality_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota municipal do IBS em providers municipais aderentes ao IBS/CBS."},"ibs_municipality_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva municipal do IBS."}}},"NfseIbscbsFederalValues":{"type":"object","additionalProperties":false,"properties":{"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota federal da CBS."},"cbs_reduction_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Redução de alíquota federal da CBS em providers municipais aderentes ao IBS/CBS."},"cbs_effective_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota efetiva federal da CBS."}}},"NfseIbscbsTotals":{"type":"object","additionalProperties":false,"description":"Totais calculados do IBS/CBS para providers municipais que serializam esse grupo. Não enviar no Ambiente Nacional.","properties":{"total_nf_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total da NFS-e usado no bloco IBS/CBS."},"ibs":{"$ref":"#/components/schemas/NfseIbscbsIbsTotals"},"cbs":{"$ref":"#/components/schemas/NfseIbscbsCbsTotals"},"government_purchase":{"$ref":"#/components/schemas/NfseIbscbsGovernmentPurchaseTotals"}}},"NfseIbscbsIbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado do IBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"state_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"},"municipality_total":{"$ref":"#/components/schemas/NfseIbscbsIbsLocationTotal"}}},"NfseIbscbsCreditPresumedTotals":{"type":"object","additionalProperties":false,"properties":{"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Percentual de crédito presumido em providers municipais aderentes ao IBS/CBS."},"amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de crédito presumido em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsIbsLocationTotal":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total consolidado do grupo correspondente."},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido do grupo correspondente em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsCbsTotals":{"type":"object","additionalProperties":false,"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Total consolidado da CBS."},"credit_presumed":{"$ref":"#/components/schemas/NfseIbscbsCreditPresumedTotals"},"deferral_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor diferido da CBS em providers municipais aderentes ao IBS/CBS."}}},"NfseIbscbsGovernmentPurchaseTotals":{"type":"object","additionalProperties":false,"properties":{"ibs_state_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota estadual do IBS em compra governamental."},"ibs_state_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor estadual do IBS em compra governamental."},"ibs_municipality_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota municipal do IBS em compra governamental."},"ibs_municipality_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor municipal do IBS em compra governamental."},"cbs_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da CBS em compra governamental."},"cbs_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CBS em compra governamental."}}},"NfseValues":{"type":"object","additionalProperties":false,"required":["total_amount"],"properties":{"total_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total do serviço."},"net_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor líquido do serviço."},"rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Alíquota do ISS."},"iss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do ISS."},"unconditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto incondicional aplicado ao serviço."},"conditional_discount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Desconto condicional aplicado ao serviço."},"ir_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do IR retido na fonte."},"pis_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do PIS retido na fonte."},"cofins_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da COFINS retida na fonte."},"inss_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do INSS retido na fonte."},"csll_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor da CSLL retida na fonte."},"other_retentions":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Outras retenções aplicadas ao serviço."},"deductions_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor total das deduções."},"intermediary_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor recebido pelo intermediário do serviço, quando o layout fiscal exigir esse destaque."},"cp_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor de Contribuição Previdenciária retido."},"pis_cofins_base_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Base de cálculo compartilhada para PIS e COFINS (vBCPisCofins no XML)."},"pis_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota do PIS (pAliqPis no XML)."},"cofins_rate":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"maximum":100,"description":"Alíquota da COFINS (pAliqCofins no XML)."},"deductions":{"type":"array","maxItems":1000,"description":"Documentos fiscais usados para dedução ou redução da base de cálculo, quando o layout fiscal permitir.","items":{"$ref":"#/components/schemas/NfseDeduction"}}}},"NfseDeduction":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["1","2","3","4","5","6","7","8","9","99"],"description":"Tipo fiscal da dedução conforme o layout aplicável."},"description":{"type":"string","maxLength":150,"description":"Descrição da dedução ou redução."},"deductible_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor do documento elegível à dedução."},"deduction_amount":{"allOf":[{"$ref":"#/components/schemas/NfseDecimalValue"}],"minimum":0,"description":"Valor efetivamente deduzido."},"document_kind":{"type":"string","description":"Tipo de documento que comprova a dedução."},"nfse_key":{"type":"string","pattern":"^[0-9]{50}$","description":"Chave de acesso da NFS-e usada como documento de dedução, com 50 dígitos quando exigida pelo Nacional."},"nfe_key":{"type":"string","pattern":"^[0-9]{44}$","description":"Chave de acesso da NF-e usada como documento de dedução, com 44 dígitos quando exigida pelo Nacional."},"other_document_number":{"type":"string","maxLength":255,"description":"Número de outro documento aceito para dedução."},"issue_date":{"type":"string","format":"date","description":"Data de emissão do documento de dedução."},"municipal_nfse":{"$ref":"#/components/schemas/NfseDeductionMunicipalNfse"},"fiscal_document":{"$ref":"#/components/schemas/NfseDeductionFiscalDocument"},"supplier":{"$ref":"#/components/schemas/NfseIntermediary","description":"Fornecedor ou prestador associado ao documento de dedução."}}},"NfseDeductionMunicipalNfse":{"type":"object","additionalProperties":false,"properties":{"municipality_code":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município da NFS-e dedutível."},"number":{"type":"string","description":"Número da NFS-e dedutível."},"verification_code":{"type":"string","pattern":"^[a-zA-Z0-9]{1,9}$","description":"Código de verificação da NFS-e dedutível."}}},"NfseDeductionFiscalDocument":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","description":"Número do documento fiscal dedutível."},"model":{"type":"string","description":"Modelo do documento fiscal dedutível."},"series":{"type":"string","description":"Série do documento fiscal dedutível."},"state":{"type":"string","maxLength":2,"description":"UF do documento fiscal dedutível."},"access_key":{"type":"string","description":"Chave de acesso do documento fiscal dedutível."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/{nfse_id}":{"get":{"operationId":"getNfse","tags":["NFS-e"],"summary":"Consultar NFS-e por ID","description":"Retorna os dados completos de uma NFS-e, incluindo URLs de download do XML e da DANFSe quando disponíveis.\n\nCampos adicionais na resposta:\n- `xml_url`: URL pública para download do XML autorizado (quando disponível).\n- `danfse_url`: URL pública para download da DANFSe em PDF (quando disponível).\n- `pdf_url`: **Compatibilidade.** (Compatibility) Alias permanente de `danfse_url` para integrações antigas. Mantido indefinidamente.","parameters":[{"name":"nfse_id","in":"path","required":true,"description":"ID da NFS-e.","schema":{"$ref":"#/components/schemas/ObjectId"}},{"$ref":"#/components/parameters/AcceptLanguage"}],"responses":{"200":{"description":"NFS-e encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseReadResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Download XML da NFS-e

> Retorna o XML autorizado da NFS-e.\
> \
> Esta rota é \*\*pública\*\* — não requer autenticação. Exige \`download\_token\` (UUID v4) na querystring,\
> emitido junto com a NFS-e e validado em par com \`nfse\_id\`. O token é permanente e compartilhável,\
> mas não derivado de dados públicos da nota — não tente recriá-lo a partir de \`\_id\` ou CNPJ.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[],"paths":{"/nfse/{nfse_id}.xml":{"get":{"operationId":"downloadNfseXml","tags":["NFS-e"],"summary":"Download XML da NFS-e","description":"Retorna o XML autorizado da NFS-e.\n\nEsta rota é **pública** — não requer autenticação. Exige `download_token` (UUID v4) na querystring,\nemitido junto com a NFS-e e validado em par com `nfse_id`. O token é permanente e compartilhável,\nmas não derivado de dados públicos da nota — não tente recriá-lo a partir de `_id` ou CNPJ.","parameters":[{"name":"nfse_id","in":"path","required":true,"description":"ID da NFS-e.","schema":{"$ref":"#/components/schemas/ObjectId"}},{"name":"download_token","in":"query","required":true,"description":"Token UUID v4 emitido com a NFS-e. Validado em par com `nfse_id`; não há fallback.","schema":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}}],"responses":{"200":{"description":"XML da NFS-e","content":{"application/xml":{"schema":{"type":"string"}}}},"400":{"description":"Querystring inválida (download_token ausente ou fora do formato UUID v4)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NFS-e ou arquivo XML não encontrado, ou par nfse_id/download_token inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}},"components":{"schemas":{"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"responses":{"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

## Download da DANFSe

> Retorna a DANFSe em PDF.\
> \
> Esta rota é \*\*pública\*\* — não requer autenticação. Exige \`download\_token\` (UUID v4) na querystring,\
> emitido junto com a NFS-e e validado em par com \`nfse\_id\`. O token é permanente e compartilhável,\
> mas não derivado de dados públicos da nota — não tente recriá-lo a partir de \`\_id\` ou CNPJ.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[],"paths":{"/nfse/{nfse_id}.pdf":{"get":{"operationId":"downloadNfseDanfse","tags":["NFS-e"],"summary":"Download da DANFSe","description":"Retorna a DANFSe em PDF.\n\nEsta rota é **pública** — não requer autenticação. Exige `download_token` (UUID v4) na querystring,\nemitido junto com a NFS-e e validado em par com `nfse_id`. O token é permanente e compartilhável,\nmas não derivado de dados públicos da nota — não tente recriá-lo a partir de `_id` ou CNPJ.","parameters":[{"name":"nfse_id","in":"path","required":true,"description":"ID da NFS-e.","schema":{"$ref":"#/components/schemas/ObjectId"}},{"name":"download_token","in":"query","required":true,"description":"Token UUID v4 emitido com a NFS-e. Validado em par com `nfse_id`; não há fallback.","schema":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}}],"responses":{"200":{"description":"DANFSe em PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Querystring inválida (download_token ausente ou fora do formato UUID v4)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NFS-e ou arquivo DANFSe não encontrado, ou par nfse_id/download_token inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}},"components":{"schemas":{"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"responses":{"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

## Cancelar NFS-e

> Solicita cancelamento de NFS-e autorizadas no provedor municipal ou nacional.\
> \
> Regras importantes:\
> \- Apenas NFS-e com status AUTHORIZED podem ser canceladas.\
> \- \`cancel\_reason\` e \`cancel\_code\` são serializados quando informados; obrigatoriedade, domínio e limites fiscais ficam a cargo da rejeição oficial do provedor/prefeitura.\
> \- \`resolve\` aceita um ou mais itens com \`nfse\_id\` ou com (\`issuer\_tax\_id\` + \`external\_id\`).\
> \- O provider efetivo define se aceita cancelamento e retorna a rejeição fiscal quando o motivo ou código não atende ao layout oficial.\
> \- O Nacional usa a política fixa do provider nacional, sem perfil municipal nem fallback municipal.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"CancelNfseRequest":{"type":"object","additionalProperties":false,"required":["resolve"],"properties":{"resolve":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CancelNfseResolve"},"description":"Lista de referências para resolução das NFS-e que serão canceladas."},"cancel_reason":{"type":"string","description":"Motivo do cancelamento da NFS-e. Serializado quando informado; obrigatoriedade e tamanho são validados pelo provedor."},"cancel_code":{"type":"integer","description":"Código de cancelamento serializado quando informado; domínio fiscal é validado pelo provedor.\nProviders com tradução canônica conhecida podem mapear esse valor para o código municipal específico.\n\n- 1: Erro na emissão\n- 2: Serviço não prestado (default)\n- 3: Erro de assinatura\n- 4: Duplicidade\n- 5: Substituição\n- 99: Outros\n"}}},"CancelNfseResolve":{"oneOf":[{"type":"object","additionalProperties":false,"required":["nfse_id"],"properties":{"nfse_id":{"$ref":"#/components/schemas/ObjectId","description":"ID interno da NFS-e que será cancelada."}}},{"type":"object","additionalProperties":false,"required":["issuer_tax_id","external_id"],"properties":{"issuer_tax_id":{"type":"string","description":"CNPJ do emissor da NFS-e (somente dígitos)."},"external_id":{"type":"string","description":"ID externo da NFS-e que será cancelada."}}}]},"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"CancelNfseResponse":{"type":"object","additionalProperties":false,"required":["canceled_ids","failed"],"properties":{"canceled_ids":{"type":"array","description":"IDs das NFS-es que tiveram cancelamento aceito e enfileirado no outbox.","items":{"$ref":"#/components/schemas/ObjectId"}},"failed":{"type":"array","description":"IDs das NFS-es que não puderam ser cancelados nesta requisição.\nInclui falhas de validação e tentativas que perderam o lock otimista\n(NFS-e já em outra operação pendente).","items":{"$ref":"#/components/schemas/CancelFailedItem"}}}},"CancelFailedItem":{"type":"object","additionalProperties":false,"required":["id","code","error","params"],"properties":{"id":{"$ref":"#/components/schemas/ObjectId","description":"Identificador público do certificado. Em `PUT /certificates/{certificate_id}`, preserva o mesmo valor enviado no path."},"code":{"type":"string","description":"Código estruturado da falha parcial."},"error":{"type":"string","description":"Motivo da falha por NFS-e. Pode ser erro de validação (status incompatível, motivo inválido)\nou de lock otimista quando a NFS-e já está em outra operação pendente."},"params":{"type":"object","additionalProperties":true,"description":"Parâmetros estruturados da falha parcial."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/cancel":{"post":{"operationId":"cancelNfses","tags":["NFS-e"],"summary":"Cancelar NFS-e","description":"Solicita cancelamento de NFS-e autorizadas no provedor municipal ou nacional.\n\nRegras importantes:\n- Apenas NFS-e com status AUTHORIZED podem ser canceladas.\n- `cancel_reason` e `cancel_code` são serializados quando informados; obrigatoriedade, domínio e limites fiscais ficam a cargo da rejeição oficial do provedor/prefeitura.\n- `resolve` aceita um ou mais itens com `nfse_id` ou com (`issuer_tax_id` + `external_id`).\n- O provider efetivo define se aceita cancelamento e retorna a rejeição fiscal quando o motivo ou código não atende ao layout oficial.\n- O Nacional usa a política fixa do provider nacional, sem perfil municipal nem fallback municipal.","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelNfseRequest"}}}},"responses":{"200":{"description":"Resultado por item. `canceled_ids` traz os IDs cujo lock foi obtido e o cancelamento foi enfileirado\nno outbox; `failed` traz os IDs que falharam por validação ou por lock pendente\n(NFS-e já em outra operação concorrente). Erros de requisição inteira inválida são lançados via 422.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelNfseResponse"}}}},"400":{"description":"Erro de validação estrutural ou regra de negócio","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Emissor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Requisição sem NFS-e elegível para cancelamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Solicitar reconciliação unitária de NFS-e

> Solicita reconciliação de uma NFS-e com o provedor municipal ou nacional.\
> \
> Este endpoint aceita NFS-e com status:\
> \- CREATED\
> \- PROCESSING\
> \- AUTHORIZED\
> \- REJECTED\
> \- CANCELED\
> \- SUBSTITUTED\
> \- ERROR\
> \- UNSYNCED (quando o sistema desistiu de consultar após dead-letter)\
> \
> A resolução aceita exatamente um item com \`nfse\_id\` ou \`issuer\_tax\_id\` + \`external\_id\`.\
> Requisições com várias NFS-e devem chamar este endpoint uma vez por documento.\
> Se o provedor retornar a NFS-e como cancelada, o status local passa para \`canceled\`.\
> No Nacional, a consulta da NFS-e autorizada não traz status de cancelamento; o provider\
> faz consulta complementar aos eventos oficiais e só confirma cancelamento com \`eventoXmlGZipB64\`\
> legível, assinado e compatível com um código terminal de cancelamento.\
> \
> A resposta retorna o ID sincronizado ou uma falha unitária quando houver.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"SyncNfseRequest":{"type":"object","additionalProperties":false,"required":["resolve"],"properties":{"resolve":{"type":"array","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/NfseResolveReference"},"description":"Referência unitária da NFS-e que será reconciliada. Aceita `nfse_id` ou `issuer_tax_id` + `external_id`."}}},"NfseResolveReference":{"oneOf":[{"type":"object","additionalProperties":false,"required":["nfse_id"],"properties":{"nfse_id":{"$ref":"#/components/schemas/ObjectId","description":"ID interno da NFS-e."}}},{"type":"object","additionalProperties":false,"required":["issuer_tax_id","external_id"],"properties":{"issuer_tax_id":{"type":"string","description":"CNPJ do emissor da NFS-e (somente dígitos)."},"external_id":{"type":"string","description":"ID externo da NFS-e."}}}]},"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"SyncNfseResponse":{"type":"object","additionalProperties":false,"required":["synced_ids","failed"],"properties":{"synced_ids":{"type":"array","items":{"$ref":"#/components/schemas/ObjectId"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/SyncFailedItem"}}}},"SyncFailedItem":{"type":"object","additionalProperties":false,"required":["id","code","error","params"],"properties":{"id":{"type":"string","description":"Identificador informado ou resolvido para a NFS-e que não pôde ser sincronizada."},"code":{"type":"string","description":"Código estruturado da falha parcial."},"error":{"type":"string","description":"Mensagem de erro retornada pelo processamento."},"params":{"type":"object","additionalProperties":true,"description":"Parâmetros estruturados da falha parcial."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/sync":{"post":{"operationId":"syncNfses","tags":["NFS-e"],"summary":"Solicitar reconciliação unitária de NFS-e","description":"Solicita reconciliação de uma NFS-e com o provedor municipal ou nacional.\n\nEste endpoint aceita NFS-e com status:\n- CREATED\n- PROCESSING\n- AUTHORIZED\n- REJECTED\n- CANCELED\n- SUBSTITUTED\n- ERROR\n- UNSYNCED (quando o sistema desistiu de consultar após dead-letter)\n\nA resolução aceita exatamente um item com `nfse_id` ou `issuer_tax_id` + `external_id`.\nRequisições com várias NFS-e devem chamar este endpoint uma vez por documento.\nSe o provedor retornar a NFS-e como cancelada, o status local passa para `canceled`.\nNo Nacional, a consulta da NFS-e autorizada não traz status de cancelamento; o provider\nfaz consulta complementar aos eventos oficiais e só confirma cancelamento com `eventoXmlGZipB64`\nlegível, assinado e compatível com um código terminal de cancelamento.\n\nA resposta retorna o ID sincronizado ou uma falha unitária quando houver.","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncNfseRequest"}}}},"responses":{"200":{"description":"Resultado unitário. `synced_ids` traz o ID cujo lock foi obtido e a consulta foi enfileirada\nno outbox; `failed` traz os IDs que falharam por validação ou por lock pendente\n(NFS-e já em outra operação como cancelamento ou substituição). Sync sobre uma NFS-e que já está\nem `sync_pending` também cai em `failed` — aguarde a operação corrente terminar antes de re-tentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncNfseResponse"}}}},"400":{"description":"Erro de validação ou regra de negócio","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Reenviar NFS-e rejeitadas ou com erro sem edição

> Reenfileira novo envio para NFS-e já persistidas em \`rejected\` ou \`error\`, sem exigir o payload fiscal completo novamente.\
> \
> Use este endpoint quando os dados fiscais salvos já estão corretos e a operação precisa apenas ser reenviada em lote.\
> O backend reconstrói o payload a partir da NFS-e vigente, usa a configuração NFS-e atual da empresa emissora,\
> realoca a referência fiscal quando aplicável e limpa dados de rejeição antes de enfileirar o novo envio.\
> \
> Regras importantes:\
> \- Aceita uma ou mais referências em \`resolve\[]\`.\
> \- Cada item pode usar \`nfse\_id\` ou \`issuer\_tax\_id\` + \`external\_id\`.\
> \- Apenas NFS-e em \`rejected\` ou \`error\`, sem operação pendente e sem evidência fiscal são reenviadas.\
> \- O resultado é parcial: uma NFS-e inválida não bloqueia o reenvio das demais.\
> \- Para alterar dados fiscais antes de reenviar, use \`POST /nfse\` com o mesmo \`external\_id\`.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"ResendNfseRequest":{"type":"object","additionalProperties":false,"required":["resolve"],"properties":{"resolve":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/NfseResolveReference"},"description":"Lista de referências para resolução das NFS-e que serão reenviadas sem edição. Aceita `nfse_id` ou `issuer_tax_id` + `external_id`."}}},"NfseResolveReference":{"oneOf":[{"type":"object","additionalProperties":false,"required":["nfse_id"],"properties":{"nfse_id":{"$ref":"#/components/schemas/ObjectId","description":"ID interno da NFS-e."}}},{"type":"object","additionalProperties":false,"required":["issuer_tax_id","external_id"],"properties":{"issuer_tax_id":{"type":"string","description":"CNPJ do emissor da NFS-e (somente dígitos)."},"external_id":{"type":"string","description":"ID externo da NFS-e."}}}]},"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"ResendNfseResponse":{"type":"object","additionalProperties":false,"required":["resent_ids","failed"],"properties":{"resent_ids":{"type":"array","description":"IDs das NFS-es que tiveram novo envio enfileirado.","items":{"$ref":"#/components/schemas/ObjectId"}},"failed":{"type":"array","description":"IDs das NFS-es que não puderam ser reenviadas nesta requisição.","items":{"$ref":"#/components/schemas/ResendNfseFailedItem"}}}},"ResendNfseFailedItem":{"type":"object","additionalProperties":false,"required":["id","code","error","params"],"properties":{"id":{"type":"string","description":"Identificador informado ou resolvido para a NFS-e que não pôde ser reenviada."},"code":{"type":"string","description":"Código estruturado da falha parcial."},"error":{"type":"string","description":"Mensagem de erro retornada para a NFS-e que não pôde ser reenviada."},"params":{"type":"object","additionalProperties":true,"description":"Parâmetros estruturados da falha parcial."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/resend":{"post":{"operationId":"resendPersistedNfses","tags":["NFS-e"],"summary":"Reenviar NFS-e rejeitadas ou com erro sem edição","description":"Reenfileira novo envio para NFS-e já persistidas em `rejected` ou `error`, sem exigir o payload fiscal completo novamente.\n\nUse este endpoint quando os dados fiscais salvos já estão corretos e a operação precisa apenas ser reenviada em lote.\nO backend reconstrói o payload a partir da NFS-e vigente, usa a configuração NFS-e atual da empresa emissora,\nrealoca a referência fiscal quando aplicável e limpa dados de rejeição antes de enfileirar o novo envio.\n\nRegras importantes:\n- Aceita uma ou mais referências em `resolve[]`.\n- Cada item pode usar `nfse_id` ou `issuer_tax_id` + `external_id`.\n- Apenas NFS-e em `rejected` ou `error`, sem operação pendente e sem evidência fiscal são reenviadas.\n- O resultado é parcial: uma NFS-e inválida não bloqueia o reenvio das demais.\n- Para alterar dados fiscais antes de reenviar, use `POST /nfse` com o mesmo `external_id`.","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendNfseRequest"}}}},"responses":{"200":{"description":"Resultado por item. `resent_ids` traz os IDs cujo novo envio foi enfileirado;\n`failed` traz NFS-e não encontradas, fora dos status elegíveis, com operação pendente, com evidência fiscal\nou que falharam por validação de cadastro/configuração no reenvio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendNfseResponse"}}}},"400":{"description":"Erro de validação do envelope","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Reemitir webhooks de NFS-e

> Reemite webhooks de NFS-e usando o status atual persistido na plataforma.\
> \
> Use este endpoint quando a NFS-e já está no estado correto no e-docs, mas o webhook correspondente\
> não foi gerado ou precisa ser reemitido sem consultar novamente a prefeitura.\
> \
> Regras importantes:\
> \- Não consulta o provedor fiscal.\
> \- Não depende de um \`webhook\_log\` anterior.\
> \- Cria novos \`webhook\_logs\` e novas entregas na outbox para os webhooks ativos que assinam o evento atual.\
> \- Bloqueia NFS-e com operação pendente (\`sync\_pending\`, \`cancellation\_pending\` ou \`substitution\_pending\`).\
> \- \`resolve\` aceita um ou mais itens com \`nfse\_id\` ou com (\`issuer\_tax\_id\` + \`external\_id\`).

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"ReplayNfseWebhookRequest":{"type":"object","additionalProperties":false,"required":["resolve"],"properties":{"resolve":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/NfseResolveReference"},"description":"Lista de referências para resolução das NFS-e que terão webhook reemitido. Aceita `nfse_id` ou `issuer_tax_id` + `external_id`."}}},"NfseResolveReference":{"oneOf":[{"type":"object","additionalProperties":false,"required":["nfse_id"],"properties":{"nfse_id":{"$ref":"#/components/schemas/ObjectId","description":"ID interno da NFS-e."}}},{"type":"object","additionalProperties":false,"required":["issuer_tax_id","external_id"],"properties":{"issuer_tax_id":{"type":"string","description":"CNPJ do emissor da NFS-e (somente dígitos)."},"external_id":{"type":"string","description":"ID externo da NFS-e."}}}]},"ObjectId":{"type":"string","description":"Identificador no formato ObjectId."},"ReplayNfseWebhookResponse":{"type":"object","additionalProperties":false,"required":["replayed_ids","skipped_ids","failed"],"properties":{"replayed_ids":{"type":"array","description":"IDs das NFS-es que tiveram ao menos um webhook log criado para entrega.","items":{"$ref":"#/components/schemas/ObjectId"}},"skipped_ids":{"type":"array","description":"IDs das NFS-es válidas que não possuíam webhook ativo assinando o evento atual.","items":{"$ref":"#/components/schemas/ObjectId"}},"failed":{"type":"array","description":"IDs das NFS-es que não puderam gerar replay por operação pendente, status sem evento ou erro técnico.","items":{"$ref":"#/components/schemas/ReplayNfseWebhookFailedItem"}}}},"ReplayNfseWebhookFailedItem":{"type":"object","additionalProperties":false,"required":["id","code","error","params"],"properties":{"id":{"$ref":"#/components/schemas/ObjectId"},"code":{"type":"string","description":"Código estruturado da falha parcial."},"error":{"type":"string","description":"Mensagem de erro retornada para a NFS-e que não pôde ter webhook reemitido."},"params":{"type":"object","additionalProperties":true,"description":"Parâmetros estruturados da falha parcial."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}},"ValidationErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}],"description":"Erro de validação (Zod ou validador de domínio). No `POST /nfse`, `error.code` é `NFSE_VALIDATION_FAILED`; `error.details[]` carrega cada campo inválido com códigos catalogados ou `VALIDATION_*` e `params.field`."}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/webhooks/replay":{"post":{"operationId":"replayNfseWebhooks","tags":["NFS-e"],"summary":"Reemitir webhooks de NFS-e","description":"Reemite webhooks de NFS-e usando o status atual persistido na plataforma.\n\nUse este endpoint quando a NFS-e já está no estado correto no e-docs, mas o webhook correspondente\nnão foi gerado ou precisa ser reemitido sem consultar novamente a prefeitura.\n\nRegras importantes:\n- Não consulta o provedor fiscal.\n- Não depende de um `webhook_log` anterior.\n- Cria novos `webhook_logs` e novas entregas na outbox para os webhooks ativos que assinam o evento atual.\n- Bloqueia NFS-e com operação pendente (`sync_pending`, `cancellation_pending` ou `substitution_pending`).\n- `resolve` aceita um ou mais itens com `nfse_id` ou com (`issuer_tax_id` + `external_id`).","parameters":[{"$ref":"#/components/parameters/AcceptLanguage"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayNfseWebhookRequest"}}}},"responses":{"200":{"description":"Resultado por item. `replayed_ids` traz os IDs com ao menos um log de webhook criado,\n`skipped_ids` traz os IDs válidos que não possuíam webhook ativo para o evento atual e `failed`\ntraz falhas por operação pendente, status sem evento público ou erro técnico.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayNfseWebhookResponse"}}}},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar perfil NFS-e do município

> Retorna o perfil operacional de NFS-e para um município (IBGE).\
> \
> Use esta rota para descobrir os provedores municipais e suas capacidades\
> antes de configurar uma empresa com \`integration=municipal\`.\
> \
> O fluxo \`integration=national\` não depende deste perfil.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"NFS-e","description":"Emissão, cancelamento, correção e sincronização de NFS-e.\n\nFluxo típico:\n1. `POST /nfse` — envia requisição com até 500 documentos fiscais independentes.\n2. Acompanhe via webhook ou `GET /nfse/{id}`.\n3. Em caso de rejeição, corrija e reenvie via `POST /nfse` ou reenvie sem editar via `POST /nfse/resend`.\n4. Para cancelar autorizada: `POST /nfse/cancel`.\n5. Para reemitir webhooks pelo estado atual: `POST /nfse/webhooks/replay`."}],"servers":[{"url":"https://sandbox.api.edocs.ixcsoft.com.br","description":"Sandbox — simulação interna, aceita certificado self-signed, sem comunicação com a prefeitura."},{"url":"https://api.edocs.ixcsoft.com.br","description":"Produção / Homologação — ambiente real, controlado por `nfse_config.environment`."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API enviada no header `x-api-key`.\n\nExistem dois níveis de chave:\n- Workspace: permite emitir NFS-e para várias empresas do mesmo workspace e pode associar webhooks/integrações via `company_id` ou `tax_id`.\n- Empresa: permite emitir NFS-e e gerir certificados apenas para a raiz do CNPJ vinculado e autoassocia webhooks/integrações à própria empresa.\n- Se a integração tiver `allowed_ips`, o acesso só é liberado quando o IP resolvido por `request.ip` estiver dentro da allowlist configurada.\n\nPara gerar a chave de workspace, crie uma integração no painel\n(sem `company_id`) e utilize o `api_key` retornado."}},"parameters":{"MunicipalityCode":{"name":"municipality_code","in":"path","required":true,"description":"Código IBGE do município (7 dígitos).","schema":{"type":"string","minLength":7,"maxLength":7}},"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Idioma preferencial para mensagens de erro (ex.: pt-BR).","schema":{"type":"string"}}},"schemas":{"NfseMunicipalityProfile":{"type":"object","additionalProperties":false,"required":["municipality","state","municipality_code","timezone","provider","provider_config"],"properties":{"municipality":{"type":"string","description":"Nome do município."},"state":{"type":"string","description":"UF."},"municipality_code":{"type":"string","description":"Código IBGE."},"timezone":{"type":"string","description":"Timezone IANA do município."},"provider":{"type":"string","description":"Slug técnico do provider municipal."},"provider_config":{"$ref":"#/components/schemas/NfseProfileProviderConfig"}}},"NfseProfileProviderConfig":{"type":"object","additionalProperties":false,"required":["active","docs_version","endpoints"],"properties":{"active":{"type":"boolean"},"description":{"type":"string"},"docs_version":{"type":"string","description":"Versão do conjunto de artefatos oficiais usados para validar o provider."},"doc_source":{"$ref":"#/components/schemas/NfseProviderArtifactSource"},"max_batch_size":{"type":"integer","minimum":1,"description":"Máximo de documentos aceito por envio. Valor `1` indica envio unitário."},"requires_certificate":{"type":"boolean","description":"Capacidade resolvida do provedor para indicar exigência de certificado digital."},"max_series_per_company":{"type":"integer","minimum":1},"max_description_length":{"type":"integer","minimum":1,"description":"Limite de caracteres da discriminação do serviço."},"generates_official_danfse":{"type":"boolean","description":"Indica se o município gera DANFSe oficial automaticamente."},"cancellation_async_confirmation":{"type":"boolean","description":"Indica se o município confirma o cancelamento de forma assíncrona (devolve a NFS-e como autorizada por um tempo até efetivar)."},"xml_encoding":{"type":"string","enum":["utf-8","iso-8859-1"],"description":"Encoding XML aceito pelo provider municipal."},"endpoints":{"$ref":"#/components/schemas/NfseProviderConfigEndpoints"},"setup_spec":{"oneOf":[{"$ref":"#/components/schemas/NfseProviderSetupSpec"},{"type":"null"}],"description":"Setup spec público do provider, sem o modelo operacional interno de referência."},"capabilities":{"type":"object","additionalProperties":true,"description":"Matriz de capacidades resolvida do provider."}}},"NfseProviderArtifactSource":{"type":"object","additionalProperties":false,"properties":{"municipality":{"type":["string","null"],"description":"Município usado como fonte oficial do artefato versionado."},"provider":{"type":["string","null"],"description":"Nome do provedor usado como fonte oficial do artefato versionado."},"documentation_url":{"type":["string","null"],"description":"URL do portal oficial consultado para manual, layout ou XSD."},"wsdl_url":{"type":["string","null"],"description":"URL oficial do WSDL publicada pelo portal do provider ou município."},"captured_at":{"type":["string","null"],"description":"Data em que os artefatos versionados foram conferidos no repositório."},"checksum":{"type":["string","null"],"description":"Checksum opcional do artefato oficial quando a coleta registrar esse valor."}}},"NfseProviderConfigEndpoints":{"type":"object","additionalProperties":false,"required":["production","homologation"],"properties":{"production":{"type":["string","null"]},"homologation":{"type":["string","null"]}}},"NfseProviderSetupSpec":{"type":"object","description":"Especificação declarativa do provider usada para montar a configuração da empresa.\n\nCampos relevantes para a configuração NFS-e:\n- `certificate.required`: define se a empresa precisa selecionar certificado.\n- `authorization`: declara os tipos de autorização técnica aceitos pelo provider.\n- `profile_settings`: declara campos dinâmicos do perfil municipal/provedor.\n- `company_settings`: declara os campos dinâmicos top-level aceitos na configuração da empresa.\n- `profile_settings[].template.visible` e `company_settings[].template.visible`: quando `true`, expõem o campo no editor de templates como `provider_settings.<key>` ou como o `template.path` literal declarado pelo provider.\n- `numbering.series_format`: indica se a série fiscal usa formato `numeric` ou `alphanumeric`.","additionalProperties":true,"properties":{"certificate":{"type":"object","additionalProperties":true},"profile_settings":{"type":"array","items":{"$ref":"#/components/schemas/NfseProviderSetupField"}},"company_settings":{"type":"array","items":{"$ref":"#/components/schemas/NfseProviderSetupField"}},"authorization":{"type":"object","additionalProperties":true,"description":"Tipos de autorização técnica aceitos pelo provider. Quando houver um único tipo, a API pode inferir o `type` no payload da empresa."},"numbering":{"type":"object","additionalProperties":false,"properties":{"series_format":{"type":"string","enum":["numeric","alphanumeric"],"description":"Formato canônico da série fiscal usada em `numbering[].series`."}}}}},"NfseProviderSetupField":{"type":"object","additionalProperties":true,"required":["key","type","required"],"properties":{"key":{"type":"string","description":"Chave declarada pelo provider. Quando exposta em template, vira `provider_settings.<key>`."},"type":{"type":"string","enum":["boolean","number","password","radio","select","text","url"]},"required":{"type":"boolean"},"sensitive":{"type":"boolean"},"template":{"type":"object","additionalProperties":false,"description":"Metadado de UI para campos já existentes no contrato do provider. Não cria campo fiscal novo.","properties":{"visible":{"type":"boolean","description":"Quando `true`, permite selecionar `provider_settings.<key>` no editor de templates."},"path":{"type":"string","description":"Path literal usado no template físico quando o contexto do provider não usa `provider_settings.<key>`."},"description":{"type":"string","description":"Descrição opcional exibida no seletor de campos do editor de templates."}}}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string","description":"Código machine-readable do erro. Detalhes em `docs/ERRORS.md`."},"message":{"type":"string","description":"Mensagem traduzida conforme Accept-Language."},"status":{"type":"integer","description":"HTTP status code."},"params":{"type":"object","description":"Dados estruturados do erro (campos referenciados, identificadores, contexto técnico). Reflete a interpolação `{{var}}` aplicada ao template da mensagem.","additionalProperties":true},"details":{"type":"array","description":"Lista de falhas estruturadas adicionais (presente quando há múltiplas falhas, ex.: validação Zod, múltiplas empresas inválidas).","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"ErrorDetail":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Código machine-readable do detalhe."},"message":{"type":"string","description":"Mensagem traduzida do detalhe conforme Accept-Language."},"params":{"type":"object","description":"Dados estruturados do detalhe (campo referenciado, identificadores, etc.).","additionalProperties":true}}}},"responses":{"UnauthorizedError":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnderMaintenance":{"description":"Sistema em manutenção programada","headers":{"Retry-After":{"description":"Data e hora prevista para o fim da manutenção no formato HTTP-date (RFC 7231).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/nfse/{municipality_code}/profile":{"get":{"operationId":"getNfseMunicipalityProfile","tags":["NFS-e"],"summary":"Consultar perfil NFS-e do município","description":"Retorna o perfil operacional de NFS-e para um município (IBGE).\n\nUse esta rota para descobrir os provedores municipais e suas capacidades\nantes de configurar uma empresa com `integration=municipal`.\n\nO fluxo `integration=national` não depende deste perfil.","parameters":[{"$ref":"#/components/parameters/MunicipalityCode"},{"$ref":"#/components/parameters/AcceptLanguage"}],"responses":{"200":{"description":"Configuração do município","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseMunicipalityProfile"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ixc-soft.gitbook.io/e-docs/nfs-e.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.