Guia de Assinaturas
Confira o guia de assinaturas para mais informações.
Endpoint responsável por listar as notas fiscais geradas a partir das cobranças de uma assinatura.
Esse recurso permite consultar todas as NFS-e emitidas (ou agendadas) para uma assinatura específica, utilizando filtros como período de emissão, status, cliente ou referência externa.
A resposta é paginada, permitindo consultar grandes volumes de notas fiscais de forma eficiente.
Quando utilizar
Utilize este endpoint quando sua integração precisar:
- consultar as notas fiscais emitidas de uma assinatura;
- acompanhar o status das emissões;
- localizar uma nota fiscal específica;
- sincronizar notas fiscais com ERPs ou sistemas fiscais;
- consultar notas emitidas dentro de um período específico;
- conciliar cobranças da assinatura com as respectivas notas fiscais.
Paginação
O retorno é paginado.
Utilize os parâmetros limit e offset para controlar a quantidade de registros retornados.
| Parâmetro | Finalidade |
|---|---|
limit | Quantidade máxima de registros retornados por requisição (máximo de 100). |
offset | Define a posição inicial da consulta. |
Exemplo:
GET /v3/subscriptions/{id}/invoices?limit=100&offset=0
RecomendadoPara assinaturas com grande quantidade de cobranças, utilize paginação para evitar consultas muito grandes.
Filtros disponíveis
Os filtros permitem restringir o retorno da consulta.
| Filtro | Finalidade |
|---|---|
status | Retorna apenas notas fiscais em determinado status. |
effectiveDate[ge] | Data inicial do período de emissão. |
effectiveDate[le] | Data final do período de emissão. |
customer | Filtra pelas notas fiscais de um cliente específico. |
externalReference | Filtra pela referência externa da nota fiscal. |
Os filtros podem ser utilizados simultaneamente para reduzir o volume de dados retornados.
Exemplo:
GET /v3/subscriptions/{id}/invoices?status=AUTHORIZED&effectiveDate[ge]=2026-01-01&effectiveDate[le]=2026-12-31Comportamentos importantes
Ao utilizar este endpoint, considere que:
- apenas notas fiscais pertencentes à assinatura informada serão retornadas;
- notas fiscais canceladas também poderão ser retornadas, caso atendam aos filtros utilizados;
- o retorno poderá ser vazio caso nenhuma nota corresponda aos critérios informados;
- a ordenação dependerá dos parâmetros
sorteorder, quando enviados; - chamadas
GETdevem ser realizadas sem body.
Exemplos de uso
Consultar todas as notas fiscais da assinatura:
GET /v3/subscriptions/{id}/invoicesConsultar apenas notas emitidas em um período:
GET /v3/subscriptions/{id}/invoices?effectiveDate[ge]=2026-01-01&effectiveDate[le]=2026-01-31Consultar apenas notas autorizadas:
GET /v3/subscriptions/{id}/invoices?status=AUTHORIZEDConsultar utilizando referência externa:
GET /v3/subscriptions/{id}/invoices?externalReference={referencia}Boas práticas
Recomendado
- Utilize filtros de período sempre que possível.
- Evite sincronizações completas em intervalos muito curtos.
- Utilize paginação em consultas recorrentes.
- Armazene o identificador das notas fiscais retornadas para futuras consultas.
- Consulte apenas assinaturas que realmente possuam emissão automática de notas configurada.
Erros comuns
400 Bad Request
400 Bad RequestPode ocorrer quando algum filtro é enviado em formato inválido.
401 Unauthorized
401 UnauthorizedA API Key não foi informada, está inválida ou pertence ao ambiente incorreto.
403 Forbidden
403 ForbiddenPode ocorrer quando a requisição GET é enviada com body preenchido.
404 Not Found
404 Not FoundOcorre quando a assinatura informada não existe ou não pertence à conta autenticada.
Impactos operacionais
Assinaturas com grande volume de cobranças podem possuir centenas de notas fiscais emitidas.
Para melhorar a performance da integração, recomenda-se:
- utilizar paginação;
- consultar apenas períodos necessários;
- evitar sincronizações completas quando houver filtros disponíveis;
- armazenar localmente os identificadores das notas já processadas.
Conteúdos relacionados
- Criar configuração para emissão de Notas Fiscais
- Atualizar configuração para emissão de Notas Fiscais
- Recuperar configuração para emissão de notas fiscais
- Remover configuração para emissão de Notas Fiscais
- Guia de Assinaturas
Forbidden. Ocorre quando o body da requisição está preenchido, chamadas de método GET precisam ter um body vazio.
Not found