> ## Documentation Index > Fetch the complete documentation index at: https://docs.notasx.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar Notas > Notas dos Prestadores vinculados à sua Conta, das mais recentes para as mais antigas. Paginação por cursor: chame sem `cursor`, depois passe o `proximo_cursor` recebido até ele vir `null`. Notas criadas no meio da paginação não bagunçam as páginas seguintes. ## OpenAPI ````yaml /openapi.json get /v1/notas openapi: 3.1.0 info: title: NotasX API description: > API de emissão de **NFS-e pelo Padrão Nacional** (Sefin Nacional + ADN). Você cadastra os Prestadores, envia o Certificado A1 de cada um e cria Notas; o NotasX monta a DPS, assina, envia à Sefin e devolve a NFS-e por consulta (e, em breve, por Webhook). ## Fluxo 1. **Chave de API**: crie no painel ou em `POST /v1/chaves-api`. O valor (`nx_...`) aparece uma única vez. 2. **Prestador**: `POST /v1/prestadores` com CNPJ, município (IBGE) e regime do Simples. 3. **Certificado**: `POST /v1/prestadores/{id}/certificado` com o `.pfx` e a senha. O CNPJ do Certificado tem de ser o do Prestador. 4. **Nota**: `POST /v1/notas` com o header `Idempotency-Key`. Resposta `202` com a Nota `pendente`. 5. **Resultado**: consulte `GET /v1/notas/{id}` até sair de `pendente`/`processando`. Com `emitida`, a NFS-e existe: `chave_acesso` (50 dígitos), `numero_nfse` e o XML em `GET /v1/notas/{id}/xml`. ## Autenticação `Authorization: Bearer `, com uma **Chave de API** (`nx_...`, para integrações) ou o **JWT de sessão** do painel. As duas agem como a mesma Conta, sobre todos os Prestadores vinculados a ela. ## Status da Nota | Status | Significado | |---|---| | `pendente` | Criada e na fila. | | `processando` | O worker está montando, assinando ou enviando a DPS. | | `emitida` | A Sefin autorizou: existe NFS-e e chave de acesso. Final. | | `rejeitada` | **Rejeição**: a Sefin recusou a DPS (`resultado_codigo` traz o código, ex. `E0123`). Final; corrija e crie outra Nota. | | `falhou` | **Falha**: sem resposta depois das tentativas, ou impedimento (Certificado ausente ou vencido, município não conveniado, número de DPS já usado fora do NotasX). Final. | Uma Nota tem uma única DPS e no máximo uma NFS-e. Novas tentativas reenviam a mesma DPS, nunca emitem outra. ## Idempotência `POST /v1/notas` exige `Idempotency-Key` (até 255 caracteres; use um UUID ou o id do pedido no seu sistema). Repetir o pedido com a mesma chave devolve **a mesma Nota** e não cria outra emissão, mesmo que o corpo mude. A chave é única por Conta e não expira. ## Ambientes Todo Prestador começa em **homologação** (produção restrita, sem valor fiscal). `POST /v1/prestadores/{id}/ativar-producao` passa a emitir em **produção**. Cada Nota guarda o Ambiente do momento em que foi criada. ## Erros Todo erro tem o mesmo corpo: `{"erro": {"codigo": "...", "mensagem": "..."}}`. Trate pelo `codigo`, que é estável; a `mensagem` é para humanos e pode mudar. Recursos de Prestadores sem vínculo com a sua Conta respondem `404`, como se não existissem. ## Limites - **Requisições**: por Conta, por minuto. Ao estourar, `429 limite_de_requisicoes` com `Retry-After`. - **Cota**: NFS-e emitidas em produção por mês. Notas de produção ainda pendentes contam contra o limite. Esgotada, `429 cota_esgotada` com `Retry-After` até o início do próximo mês (horário de Brasília). Homologação não consome Cota. Consulte em `GET /v1/cota`. version: 0.1.2 servers: - url: https://notasx-api.fly.dev description: Produção da API (Prestadores em homologação ou produção) security: [] tags: - name: Notas description: Criar e acompanhar Notas até virarem NFS-e (ou Rejeição/Falha). - name: Prestadores description: 'Quem emite: CNPJ, município, regime, Certificado A1 e Ambiente.' - name: Chaves de API description: Credenciais das integrações. O valor só aparece na criação. - name: Conta description: 'Configuração e uso da Conta: Webhook e Cota.' paths: /v1/notas: get: tags: - Notas summary: Listar Notas description: >- Notas dos Prestadores vinculados à sua Conta, das mais recentes para as mais antigas. Paginação por cursor: chame sem `cursor`, depois passe o `proximo_cursor` recebido até ele vir `null`. Notas criadas no meio da paginação não bagunçam as páginas seguintes. operationId: listar_v1_notas_get parameters: - name: prestador_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: Só as Notas deste Prestador. title: Prestador Id description: Só as Notas deste Prestador. - name: status in: query required: false schema: anyOf: - enum: - pendente - processando - emitida - rejeitada - falhou - cancelada - substituida type: string - type: 'null' description: Só as Notas neste status. title: Status description: Só as Notas neste status. - name: limite in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Notas por página (1 a 100). default: 50 title: Limite description: Notas por página (1 a 100). - name: cursor in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: O `proximo_cursor` da página anterior. title: Cursor description: O `proximo_cursor` da página anterior. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginaNotas' '401': description: >- Sem credencial, ou Chave de API inválida/revogada, ou JWT de sessão expirado. headers: WWW-Authenticate: description: Sempre `Bearer`. schema: type: string content: application/json: examples: nao_autenticado: summary: nao_autenticado value: erro: codigo: nao_autenticado mensagem: Credencial ausente, inválida ou revogada. schema: $ref: '#/components/schemas/ErroResposta' '422': description: >- Corpo, parâmetro ou regra de negócio inválidos. `requisicao_invalida` lista os campos com problema. content: application/json: examples: requisicao_invalida: summary: requisicao_invalida value: erro: codigo: requisicao_invalida mensagem: 'corpo.cnpj: String should match pattern ''^\d{14}$''' schema: $ref: '#/components/schemas/ErroResposta' '429': description: >- Limite de requisições por minuto ou Cota mensal esgotada. Respeite o header `Retry-After`. headers: Retry-After: description: Segundos até poder tentar de novo. schema: type: integer content: application/json: examples: limite_de_requisicoes: summary: limite_de_requisicoes value: erro: codigo: limite_de_requisicoes mensagem: Muitas requisições; tente de novo em instantes. schema: $ref: '#/components/schemas/ErroResposta' security: - Chave de API: [] components: schemas: PaginaNotas: properties: itens: items: $ref: '#/components/schemas/Nota' type: array title: Itens description: Notas desta página, das mais recentes para as mais antigas. proximo_cursor: anyOf: - type: string format: uuid - type: 'null' title: Proximo Cursor description: Passe em `cursor` para buscar a próxima página; `null` na última. type: object required: - itens - proximo_cursor title: PaginaNotas ErroResposta: properties: erro: $ref: '#/components/schemas/Erro' type: object required: - erro title: ErroResposta description: Corpo de toda resposta de erro (4xx e 5xx). examples: - erro: codigo: nao_encontrado mensagem: Nota não encontrada. Nota: properties: id: type: string format: uuid title: Id description: Id da Nota no NotasX. prestador_id: type: string format: uuid title: Prestador Id description: Prestador que emite. ambiente: type: string enum: - homologacao - producao title: Ambiente description: Ambiente do Prestador quando a Nota foi criada. Não muda. status: type: string enum: - pendente - processando - emitida - rejeitada - falhou - cancelada - substituida title: Status description: >- `pendente` → `processando` → `emitida`, `rejeitada` ou `falhou` (finais). `cancelada` e `substituida` são reservados para eventos futuros. chave_idempotencia: type: string title: Chave Idempotencia description: O `Idempotency-Key` do pedido que criou a Nota. competencia: type: string format: date title: Competencia description: Data de Competência informada na criação. dados: $ref: '#/components/schemas/Servico-Output' tomador: anyOf: - $ref: '#/components/schemas/Tomador' - type: 'null' numero_dps: anyOf: - type: integer - type: 'null' title: Numero Dps description: >- Número da DPS, reservado no primeiro envio e reaproveitado nas novas tentativas. chave_acesso: anyOf: - type: string - type: 'null' title: Chave Acesso description: Chave de acesso da NFS-e (50 dígitos). Só existe com `emitida`. numero_nfse: anyOf: - type: string - type: 'null' title: Numero Nfse description: Número da NFS-e atribuído pela Sefin. resultado_codigo: anyOf: - type: string - type: 'null' title: Resultado Codigo description: >- Em `rejeitada`, os códigos da Sefin (ex.: `E0123`); em `falhou`, `impedimento` ou `sem_resposta`. resultado_mensagem: anyOf: - type: string - type: 'null' title: Resultado Mensagem description: Explicação do resultado, quando houver. criada_em: type: string format: date-time title: Criada Em description: Quando a Nota foi criada. atualizada_em: type: string format: date-time title: Atualizada Em description: Última mudança (de status ou de resultado). type: object required: - id - prestador_id - ambiente - status - chave_idempotencia - competencia - dados - tomador - numero_dps - chave_acesso - numero_nfse - resultado_codigo - resultado_mensagem - criada_em - atualizada_em title: Nota examples: - ambiente: homologacao atualizada_em: '2026-11-11T21:40:06Z' chave_acesso: '24081022242404473000102000000000002426114744866240' chave_idempotencia: pedido-2026-000123 competencia: '2026-11-11' criada_em: '2026-11-11T21:40:00Z' dados: ctrib_nac: '010101' descricao: Desenvolvimento de software sob encomenda - novembro/2026 valor_servico: '1500.00' id: ec73f621-e696-41bb-af2e-a6facb8e2be1 numero_dps: 2 numero_nfse: '24' prestador_id: 3891f091-65d6-4a88-ac60-72dbe3e98319 status: emitida tomador: documento: '11222333000181' email: financeiro@cliente.com.br endereco: bairro: Centro cep: '59000000' codigo_municipio: '2408102' logradouro: Av. Exemplo numero: '100' nome: Cliente Exemplo LTDA Erro: properties: codigo: type: string title: Codigo description: Código estável, em snake_case, para tratar o erro no seu código. examples: - nao_encontrado mensagem: type: string title: Mensagem description: >- Explicação em português para humanos. Pode mudar; não compare com ela. examples: - Nota não encontrada. type: object required: - codigo - mensagem title: Erro Servico-Output: properties: ctrib_nac: type: string pattern: ^\d{6}$ title: Ctrib Nac description: >- Código de Tributação Nacional (`cTribNac`): item, subitem e desdobro da lista de serviços da LC 116/2003. Ex.: `010101` = análise e desenvolvimento de sistemas. examples: - '010101' descricao: type: string maxLength: 2000 minLength: 1 title: Descricao description: Discriminação do serviço, como sairá na NFS-e. examples: - Desenvolvimento de software sob encomenda - novembro/2026 valor_servico: type: string title: Valor Servico description: >- Valor do serviço em reais, com até 2 casas. Devolvido como texto (`"1500.00"`). examples: - '1500.00' codigo_nbs: anyOf: - type: string pattern: ^\d{9}$ - type: 'null' title: Codigo Nbs description: Código NBS (Nomenclatura Brasileira de Serviços), opcional. examples: - '115013000' iss_retido: type: boolean title: Iss Retido description: '`true` se o ISS for retido pelo Tomador.' default: false aliquota_iss: anyOf: - type: string - type: 'null' title: Aliquota Iss description: >- Alíquota do ISS como fração (`0.05` = 5%). Hoje é ignorada: nos municípios conveniados a alíquota vem da parametrização municipal. examples: - '0.05' type: object required: - ctrib_nac - descricao - valor_servico title: Servico description: O serviço prestado e o valor. Tomador: properties: documento: type: string pattern: ^(\d{11}|\d{14})$ title: Documento description: CPF (11) ou CNPJ (14 dígitos), só dígitos. examples: - '11222333000181' nome: anyOf: - type: string maxLength: 300 - type: 'null' title: Nome description: Nome ou razão social. examples: - Cliente Exemplo LTDA email: anyOf: - type: string maxLength: 80 - type: 'null' title: Email description: E-mail do Tomador, registrado na NFS-e. examples: - financeiro@cliente.com.br fone: anyOf: - type: string pattern: ^\d{6,20}$ - type: 'null' title: Fone description: Telefone, só dígitos. examples: - '84999990000' endereco: anyOf: - $ref: '#/components/schemas/Endereco' - type: 'null' type: object required: - documento title: Tomador description: 'Quem contratou o serviço. Opcional: a Sefin aceita DPS sem Tomador.' Endereco: properties: codigo_municipio: type: string pattern: ^\d{7}$ title: Codigo Municipio description: Código IBGE do município. examples: - '2408102' cep: anyOf: - type: string pattern: ^\d{8}$ - type: 'null' title: Cep description: CEP, só dígitos. examples: - '59000000' logradouro: type: string maxLength: 255 minLength: 1 title: Logradouro description: Rua, avenida etc. examples: - Av. Exemplo numero: type: string maxLength: 60 minLength: 1 title: Numero description: Número; use `S/N` se não houver. examples: - '100' complemento: anyOf: - type: string maxLength: 156 - type: 'null' title: Complemento description: Complemento, opcional. examples: - Sala 2 bairro: type: string maxLength: 60 minLength: 1 title: Bairro description: Bairro. examples: - Centro type: object required: - codigo_municipio - logradouro - numero - bairro title: Endereco description: Endereço nacional do Tomador. Vai para a DPS só se vier completo. securitySchemes: Chave de API: type: http description: >- `Authorization: Bearer nx_...` com uma Chave de API, ou o JWT de sessão do painel (Supabase Auth). As duas credenciais representam a mesma Conta. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.