# Referências

Utilitários de consulta para apoiar a emissão de NFS-e.

Endpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`). Todos suportam paginação por cursor e seleção de campos via `fields`.

## Listar municípios IBGE

> Lista municípios da base de referências por busca textual, UF ou código IBGE.\
> Use \`GET /references/municipalities/{municipality\_code}\` quando precisar consultar um município específico.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"MunicipalityReferenceListResponse":{"type":"object","additionalProperties":false,"required":["items","paginate"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MunicipalityReferenceItem"}},"paginate":{"$ref":"#/components/schemas/CursorPaginateMeta"}}},"MunicipalityReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código IBGE)."},"municipality":{"type":["string","null"],"description":"Nome do município."},"state":{"type":["string","null"],"description":"UF."},"municipality_code":{"type":["string","null"],"description":"Código IBGE."},"key":{"type":["string","null"],"description":"Chave normalizada usada na busca."}}},"CursorPaginateMeta":{"type":"object","additionalProperties":false,"required":["limit","has_next_page","has_previous_page","start_cursor","end_cursor"],"properties":{"limit":{"type":"integer","minimum":10,"maximum":100},"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":{"ValidationError":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"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":{"/references/municipalities":{"get":{"operationId":"listReferenceMunicipalities","tags":["Referências"],"summary":"Listar municípios IBGE","description":"Lista municípios da base de referências por busca textual, UF ou código IBGE.\nUse `GET /references/municipalities/{municipality_code}` quando precisar consultar um município específico.","parameters":[{"name":"q","in":"query","required":false,"description":"Busca textual por município, sem diferenciar acentos.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"UF usada para filtrar municípios.","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"municipality_code","in":"query","required":false,"description":"Código IBGE usado para filtrar a listagem.","schema":{"type":"string","minLength":7,"maxLength":7}},{"name":"cursor","in":"query","required":false,"description":"Cursor retornado na página anterior.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página.","schema":{"type":"integer","minimum":10,"maximum":500,"default":10}},{"name":"fields","in":"query","required":false,"description":"Campos desejados na resposta, separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"Municípios encontrados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MunicipalityReferenceListResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar município IBGE

> Consulta um município específico da base de referências pelo código IBGE.\
> A rota canônica é plural: \`/references/municipalities/{municipality\_code}\`.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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}}},"schemas":{"MunicipalityReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código IBGE)."},"municipality":{"type":["string","null"],"description":"Nome do município."},"state":{"type":["string","null"],"description":"UF."},"municipality_code":{"type":["string","null"],"description":"Código IBGE."},"key":{"type":["string","null"],"description":"Chave normalizada usada na busca."}}},"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":{"/references/municipalities/{municipality_code}":{"get":{"operationId":"getReferenceMunicipality","tags":["Referências"],"summary":"Consultar município IBGE","description":"Consulta um município específico da base de referências pelo código IBGE.\nA rota canônica é plural: `/references/municipalities/{municipality_code}`.","parameters":[{"$ref":"#/components/parameters/MunicipalityCode"}],"responses":{"200":{"description":"Município encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MunicipalityReferenceItem"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Município não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Listar CNAEs

> Lista CNAEs da base de referências por busca textual, seção ou código.\
> Use \`GET /references/cnaes/{code\_digits}\` quando precisar consultar um CNAE específico.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"CnaeReferenceListResponse":{"type":"object","additionalProperties":false,"required":["items","paginate"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CnaeReferenceItem"}},"paginate":{"$ref":"#/components/schemas/CursorPaginateMeta"}}},"CnaeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código CNAE de 7 dígitos)."},"code":{"type":["string","null"],"description":"Código CNAE formatado."},"code_digits":{"type":["string","null"],"description":"Código CNAE sem formatação (7 dígitos)."},"description":{"type":["string","null"],"description":"Descrição oficial da subclasse CNAE."},"section":{"type":["string","null"],"description":"Seção CNAE."},"division":{"type":["string","null"],"description":"Divisão CNAE."},"group":{"type":["string","null"],"description":"Grupo CNAE."},"class":{"type":["string","null"],"description":"Classe CNAE."}}},"CursorPaginateMeta":{"type":"object","additionalProperties":false,"required":["limit","has_next_page","has_previous_page","start_cursor","end_cursor"],"properties":{"limit":{"type":"integer","minimum":10,"maximum":100},"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":{"ValidationError":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"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":{"/references/cnaes":{"get":{"operationId":"listReferenceCnaes","tags":["Referências"],"summary":"Listar CNAEs","description":"Lista CNAEs da base de referências por busca textual, seção ou código.\nUse `GET /references/cnaes/{code_digits}` quando precisar consultar um CNAE específico.","parameters":[{"name":"q","in":"query","required":false,"description":"Busca textual por descrição, código formatado ou código sem formatação.","schema":{"type":"string"}},{"name":"code_digits","in":"query","required":false,"description":"Código CNAE sem formatação usado para filtrar a listagem.","schema":{"type":"string","minLength":7,"maxLength":7}},{"name":"section","in":"query","required":false,"description":"Seção CNAE usada para filtrar a listagem.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor retornado na página anterior.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página.","schema":{"type":"integer","minimum":10,"maximum":500,"default":10}},{"name":"fields","in":"query","required":false,"description":"Campos desejados na resposta, separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"CNAEs encontrados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CnaeReferenceListResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar CNAE

> Consulta um CNAE específico da base de referências pelo código sem formatação.\
> A rota canônica é plural: \`/references/cnaes/{code\_digits}\`.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"CnaeCodeDigits":{"name":"code_digits","in":"path","required":true,"description":"Código CNAE sem formatação (7 dígitos).","schema":{"type":"string","minLength":7,"maxLength":7}}},"schemas":{"CnaeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código CNAE de 7 dígitos)."},"code":{"type":["string","null"],"description":"Código CNAE formatado."},"code_digits":{"type":["string","null"],"description":"Código CNAE sem formatação (7 dígitos)."},"description":{"type":["string","null"],"description":"Descrição oficial da subclasse CNAE."},"section":{"type":["string","null"],"description":"Seção CNAE."},"division":{"type":["string","null"],"description":"Divisão CNAE."},"group":{"type":["string","null"],"description":"Grupo CNAE."},"class":{"type":["string","null"],"description":"Classe CNAE."}}},"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":{"/references/cnaes/{code_digits}":{"get":{"operationId":"getReferenceCnae","tags":["Referências"],"summary":"Consultar CNAE","description":"Consulta um CNAE específico da base de referências pelo código sem formatação.\nA rota canônica é plural: `/references/cnaes/{code_digits}`.","parameters":[{"$ref":"#/components/parameters/CnaeCodeDigits"}],"responses":{"200":{"description":"CNAE encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CnaeReferenceItem"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"CNAE não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Listar códigos nacionais de serviço

> Lista códigos nacionais de serviço (\`cTribNac\`) da base de referências por busca textual ou código.\
> Use \`GET /references/service-national-codes/{code}\` quando precisar consultar um código específico.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"ServiceNationalCodeReferenceListResponse":{"type":"object","additionalProperties":false,"required":["items","paginate"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceNationalCodeReferenceItem"}},"paginate":{"$ref":"#/components/schemas/CursorPaginateMeta"}}},"ServiceNationalCodeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código nacional do serviço com 6 dígitos)."},"code":{"type":["string","null"],"description":"Código nacional do serviço (`cTribNac`)."},"description":{"type":["string","null"],"description":"Descrição oficial do serviço usada no Ambiente Nacional."}}},"CursorPaginateMeta":{"type":"object","additionalProperties":false,"required":["limit","has_next_page","has_previous_page","start_cursor","end_cursor"],"properties":{"limit":{"type":"integer","minimum":10,"maximum":100},"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":{"ValidationError":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"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":{"/references/service-national-codes":{"get":{"operationId":"listReferenceServiceNationalCodes","tags":["Referências"],"summary":"Listar códigos nacionais de serviço","description":"Lista códigos nacionais de serviço (`cTribNac`) da base de referências por busca textual ou código.\nUse `GET /references/service-national-codes/{code}` quando precisar consultar um código específico.","parameters":[{"name":"q","in":"query","required":false,"description":"Busca textual por descrição ou código.","schema":{"type":"string"}},{"name":"code","in":"query","required":false,"description":"Código nacional de serviço usado para filtrar a listagem.","schema":{"type":"string","minLength":6,"maxLength":6}},{"name":"cursor","in":"query","required":false,"description":"Cursor retornado na página anterior.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página.","schema":{"type":"integer","minimum":10,"maximum":500,"default":10}},{"name":"fields","in":"query","required":false,"description":"Campos desejados na resposta, separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"Códigos nacionais de serviço encontrados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNationalCodeReferenceListResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar código nacional de serviço

> Consulta um código nacional de serviço específico da base de referências.\
> A rota canônica é plural: \`/references/service-national-codes/{code}\`.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"ServiceNationalCode":{"name":"code","in":"path","required":true,"description":"Código nacional de serviço (`cTribNac`) com 6 dígitos.","schema":{"type":"string","minLength":6,"maxLength":6}}},"schemas":{"ServiceNationalCodeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código nacional do serviço com 6 dígitos)."},"code":{"type":["string","null"],"description":"Código nacional do serviço (`cTribNac`)."},"description":{"type":["string","null"],"description":"Descrição oficial do serviço usada no Ambiente Nacional."}}},"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":{"/references/service-national-codes/{code}":{"get":{"operationId":"getReferenceServiceNationalCode","tags":["Referências"],"summary":"Consultar código nacional de serviço","description":"Consulta um código nacional de serviço específico da base de referências.\nA rota canônica é plural: `/references/service-national-codes/{code}`.","parameters":[{"$ref":"#/components/parameters/ServiceNationalCode"}],"responses":{"200":{"description":"Código nacional de serviço encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNationalCodeReferenceItem"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Código nacional de serviço não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Listar códigos NBS

> Lista códigos NBS (\`cNBS\`) da base de referências por busca textual ou código.\
> Use \`GET /references/nbs-codes/{code}\` quando precisar consultar um código específico.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"NbsCodeReferenceListResponse":{"type":"object","additionalProperties":false,"required":["items","paginate"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/NbsCodeReferenceItem"}},"paginate":{"$ref":"#/components/schemas/CursorPaginateMeta"}}},"NbsCodeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código NBS com 9 dígitos)."},"code":{"type":["string","null"],"description":"Código NBS (`cNBS`)."},"description":{"type":["string","null"],"description":"Descrição oficial do código NBS."}}},"CursorPaginateMeta":{"type":"object","additionalProperties":false,"required":["limit","has_next_page","has_previous_page","start_cursor","end_cursor"],"properties":{"limit":{"type":"integer","minimum":10,"maximum":100},"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":{"ValidationError":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"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":{"/references/nbs-codes":{"get":{"operationId":"listReferenceNbsCodes","tags":["Referências"],"summary":"Listar códigos NBS","description":"Lista códigos NBS (`cNBS`) da base de referências por busca textual ou código.\nUse `GET /references/nbs-codes/{code}` quando precisar consultar um código específico.","parameters":[{"name":"q","in":"query","required":false,"description":"Busca textual por descrição ou código.","schema":{"type":"string"}},{"name":"code","in":"query","required":false,"description":"Código NBS usado para filtrar a listagem.","schema":{"type":"string","minLength":9,"maxLength":9}},{"name":"cursor","in":"query","required":false,"description":"Cursor retornado na página anterior.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página.","schema":{"type":"integer","minimum":10,"maximum":500,"default":10}},{"name":"fields","in":"query","required":false,"description":"Campos desejados na resposta, separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"Códigos NBS encontrados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NbsCodeReferenceListResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnderMaintenance"}}}}}}
```

## Consultar código NBS

> Consulta um código NBS específico da base de referências.\
> A rota canônica é plural: \`/references/nbs-codes/{code}\`.

```json
{"openapi":"3.1.1","info":{"title":"API IXC E-Docs - Integração x-api-key","version":"0.1.0"},"tags":[{"name":"Referências","description":"Utilitários de consulta para apoiar a emissão de NFS-e.\n\nEndpoints somente leitura para busca de CEP, consulta de CNPJ, municípios IBGE, CNAEs, códigos nacionais de serviço (`cTribNac`) e códigos NBS (`cNBS`).\nTodos suportam paginação por cursor e seleção de campos via `fields`."}],"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":{"NbsCode":{"name":"code","in":"path","required":true,"description":"Código NBS (`cNBS`) com 9 dígitos.","schema":{"type":"string","minLength":9,"maxLength":9}}},"schemas":{"NbsCodeReferenceItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","description":"Identificador lógico do item (código NBS com 9 dígitos)."},"code":{"type":["string","null"],"description":"Código NBS (`cNBS`)."},"description":{"type":["string","null"],"description":"Descrição oficial do código NBS."}}},"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":{"/references/nbs-codes/{code}":{"get":{"operationId":"getReferenceNbsCode","tags":["Referências"],"summary":"Consultar código NBS","description":"Consulta um código NBS específico da base de referências.\nA rota canônica é plural: `/references/nbs-codes/{code}`.","parameters":[{"$ref":"#/components/parameters/NbsCode"}],"responses":{"200":{"description":"Código NBS encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NbsCodeReferenceItem"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Código NBS não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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/referencias.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.