Prévia: a API abre junto com o painel.

Referência da API

Gerada a partir do contrato openapi.yaml (OpenAPI 3.1, versão 1.0.0-previa). Endereço base: https://api.nfseia.com.br/v1. Autenticação, ambientes e idempotência estão em Autenticação; erros e limites, em Erros e limites.

• Notas: Emitir nota, Listar notas, Consultar nota, Cancelar nota, Baixar o XML, Baixar o PDF, Reenviar a nota por e-mail.
• Recorrências: Criar recorrência, Listar recorrências, Consultar recorrência, Editar, pausar ou retomar, Encerrar recorrência.
• Tomadores: Salvar tomador, Listar e buscar tomadores, Consultar tomador, Editar tomador, Excluir tomador.
• Consultas: Consultar CNPJ, Buscar código de serviço.
• Gatilhos: Criar gatilho de pagamento, Listar gatilhos, Consultar gatilho, Editar ou pausar gatilho, Excluir gatilho, Trocar o segredo do gatilho, Receber aviso de pagamento.
• Webhooks: Cadastrar webhook, Listar webhooks, Consultar webhook, Editar, pausar ou reativar webhook, Excluir webhook, Trocar o segredo do webhook, Listar entregas, Reenviar entrega.
• Empresa: Consultar empresa, Gerar link de envio do certificado.

Notas

Emissão, consulta, cancelamento, XML, PDF e reenvio por e-mail da nota fiscal de serviço.

Ciclo de vida da nota:

1. Reserva (interna, não aparece na API): numa só transação, o NFSeIA reserva a referencia_externa para a empresa e o ambiente, numera a DPS e grava o Id dela, antes de qualquer envio. Pedido concorrente com a mesma referência, mesmo com outra Idempotency-Key, recebe essa mesma nota (pendente ou final), nunca uma segunda DPS.
2. pendente, com o motivo em pendencia.motivo:
   • aguardando_sefin: enviada e sem resposta no prazo. O NFSeIA consulta pelo Id da DPS em 30 s, 2 min, 10 min, 1 h e 6 h.
   • conferindo_identidade: a SEFIN disse que a DPS já existe (E0014), a consulta foi inconclusiva ou o XML recebido não confere com a DPS enviada. O NFSeIA busca a NFS-e pela chave e confere se ela é mesmo desta DPS antes de adotar.
   • colisao_numeracao: o número da DPS foi usado fora do NFSeIA (por exemplo no emissor do governo). A nota não é adotada nem reenviada; o e-mail da empresa é avisado.
   • requer_intervencao: as consultas acabaram sem resposta definitiva. O e-mail da empresa e o evento nota.pendente avisam, e o suporte resolve pelo chamado.
3. Estados finais: autorizada (número, chave de acesso, XML e PDF), rejeitada (recusa definitiva da SEFIN, conferida pelo Id da DPS: a nota não existe lá) e cancelada.

A referência e o número da DPS só são liberados quando a nota fica rejeitada. Em pendente, por qualquer motivo, os dois continuam presos à nota, sem prazo: nada é renumerado nem reenviado com outro Id, e repetir a referência devolve a nota pendente.

Emitir nota

POST/notas

Escopo: notas:emitir. Exige Idempotency-Key.

Emite uma nota fiscal de serviço em nome da empresa da chave. O prestador, a série, o número da DPS, o município emissor e o ambiente vêm da empresa e da chave; não envie.

Campos de servico e valores que você omitir vêm dos padrões da nota da empresa (padroes_da_nota em GET /empresa, definidos no cadastro), campo a campo. Depois da mistura, a nota inteira passa pela mesma validação. Se o tomador já estiver salvo em /tomadores, basta o documento; os outros dados vêm do cadastro dele.

A referencia_externa é reservada, junto com o número da DPS, antes de qualquer envio (veja o ciclo de vida em Notas). Os prefixos pagamento:, recorrencia: e mcp: são reservados (400 referencia_reservada).

Respostas:

• 201: autorizada.
• 202: pendente, com o motivo em pendencia.motivo (por exemplo, a SEFIN não respondeu em 25 s). Acompanhe por webhook ou por GET /notas/{id}.
• 200: a referencia_externa já tinha nota não rejeitada (autorizada, pendente ou cancelada), inclusive de um pedido concorrente com outra Idempotency-Key. Volta essa nota, com o cabeçalho NFSeIA-Recurso-Existente: true, e nada é emitido.
• 400 dados_invalidos: nada foi enviado à SEFIN.
• 422 nota_rejeitada: recusa definitiva da SEFIN, conferida pelo Id da DPS; a nota fica guardada como rejeitada e a referência é liberada. Recusa que ainda precisa de conferência (por exemplo "DPS já existe") volta como 202 pendente.

No ambiente de teste, coloque [simular:rejeitada] ou [simular:pendente] na descrição do serviço para ver esses caminhos; a pendente vira autorizada em cerca de 1 minuto.

Corpo

Pedido de emissão. Campo desconhecido é recusado. Não envie prestador, série, número, município emissor nem ambiente: vêm da empresa e da chave.

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/notas' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "referencia_externa": "pedido-1042",
  "tomador": {
    "documento": "12345678000195"
  },
  "valores": {
    "valor_servico": "1500.00"
  }
}'

Outro corpo: tudo explícito, tomador ainda não salvo.

{
  "referencia_externa": "pedido-1043",
  "competencia": "2026-11-05",
  "tomador": {
    "documento": "12.345.678/0001-95",
    "nome": "Padaria Pão Quente Ltda",
    "email": "[email protected]",
    "endereco": {
      "municipio": "4106902",
      "cep": "80020-310",
      "logradouro": "Rua XV de Novembro",
      "numero": "1000",
      "bairro": "Centro"
    }
  },
  "servico": {
    "codigo_tributacao_nacional": "010801",
    "codigo_nbs": null,
    "descricao": "Manutenção do site, novembro de 2026",
    "municipio_prestacao": "4106902"
  },
  "valores": {
    "valor_servico": "1500.00",
    "retencao_iss": "nao_retido",
    "percentual_tributos_simples": "6.00"
  },
  "enviar_email": true
}

Respostas

• 200: A referencia_externa já tinha nota. Volta a nota existente e nada é emitido. Nota.
• 201: Nota autorizada. Nota.
• 202: A SEFIN não respondeu a tempo. A nota fica pendente e o NFSeIA resolve sozinho. Nota.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 402: Teste grátis encerrado, cota do mês esgotada ou assinatura em atraso. Códigos: cota_esgotada.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 409: A mesma Idempotency-Key está em uso por outra requisição ou veio com outro corpo. Códigos: idempotencia_em_andamento, idempotencia_reutilizada.
• 422: A SEFIN recusou a nota. Ela fica guardada como rejeitada, com o id em nota_id. Códigos: nota_rejeitada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
  "ambiente": "producao",
  "status": "autorizada",
  "origem": "api",
  "referencia_externa": "pedido-1042",
  "numero": "18",
  "chave_acesso": "41069021245723174000110000000000001826117319502647",
  "dps": {
    "id": "DPS410690224572317400011000001000000000000042",
    "serie": "1",
    "numero": "42"
  },
  "competencia": "2026-11-05",
  "municipio_emissor": "4106902",
  "prestador": {
    "cnpj": "45723174000110",
    "inscricao_municipal": "1234567",
    "simples_nacional": "me_epp",
    "apuracao_simples": "tudo_pelo_simples"
  },
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda",
    "inscricao_municipal": null,
    "endereco": {
      "municipio": "4106902",
      "cep": "80020310",
      "logradouro": "Rua XV de Novembro",
      "numero": "1000",
      "complemento": null,
      "bairro": "Centro"
    },
    "telefone": null,
    "email": "[email protected]"
  },
  "intermediario": null,
  "servico": {
    "codigo_tributacao_nacional": "010801",
    "codigo_nbs": null,
    "descricao": "Manutenção do site, novembro de 2026",
    "municipio_prestacao": "4106902"
  },
  "valores": {
    "valor_servico": "1500.00",
    "retencao_iss": "nao_retido",
    "aliquota_iss": null,
    "percentual_tributos_simples": "6.00"
  },
  "pendencia": null,
  "rejeicao": null,
  "cancelamento": null,
  "emails": [
    {
      "destinatario": "tomador",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-05T14:03:20-03:00"
    },
    {
      "destinatario": "emissor",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-05T14:03:20-03:00"
    }
  ],
  "links": {
    "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
    "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf",
    "consulta_publica": "https://www.nfse.gov.br/consultapublica"
  },
  "recorrencia_id": null,
  "gatilho_id": null,
  "criada_em": "2026-11-05T14:03:09-03:00",
  "autorizada_em": "2026-11-05T14:03:12-03:00",
  "atualizada_em": "2026-11-05T14:03:20-03:00"
}

Listar notas

GET/notas

Escopo: notas:ler.

Lista as notas do ambiente da chave, da mais nova para a mais antiga, com paginação por cursor. Filtrando pela referencia_externa, a primeira da lista é a tentativa vigente (a única não rejeitada: autorizada, pendente ou cancelada), se houver; as demais são o histórico de tentativas rejeitadas.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/notas?referencia_externa=pedido-1042' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Página de notas. Lista de Nota em dados, com proximo_cursor.
• 400: Requisição malformada. Códigos: requisicao_invalida.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
      "ambiente": "producao",
      "status": "autorizada",
      "origem": "api",
      "referencia_externa": "pedido-1042",
      "numero": "18",
      "chave_acesso": "41069021245723174000110000000000001826117319502647",
      "dps": {
        "id": "DPS410690224572317400011000001000000000000042",
        "serie": "1",
        "numero": "42"
      },
      "competencia": "2026-11-05",
      "municipio_emissor": "4106902",
      "prestador": {
        "cnpj": "45723174000110",
        "inscricao_municipal": "1234567",
        "simples_nacional": "me_epp",
        "apuracao_simples": "tudo_pelo_simples"
      },
      "tomador": {
        "documento": "12345678000195",
        "nome": "Padaria Pão Quente Ltda",
        "email": "[email protected]"
      },
      "intermediario": null,
      "servico": {
        "codigo_tributacao_nacional": "010801",
        "codigo_nbs": null,
        "descricao": "Manutenção do site, novembro de 2026",
        "municipio_prestacao": "4106902"
      },
      "valores": {
        "valor_servico": "1500.00",
        "retencao_iss": "nao_retido",
        "percentual_tributos_simples": "6.00"
      },
      "pendencia": null,
      "rejeicao": null,
      "cancelamento": null,
      "emails": [],
      "links": {
        "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
        "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf",
        "consulta_publica": "https://www.nfse.gov.br/consultapublica"
      },
      "recorrencia_id": null,
      "gatilho_id": null,
      "criada_em": "2026-11-05T14:03:09-03:00",
      "autorizada_em": "2026-11-05T14:03:12-03:00",
      "atualizada_em": "2026-11-05T14:03:12-03:00"
    }
  ],
  "proximo_cursor": "eyJpZCI6Im5vdGFfMDFKQzhaNE0zUUs3VDJWOVg1QjZOMVIwUEQifQ"
}

Consultar nota

GET/notas/{id}

Escopo: notas:ler.

Devolve a nota com o estado atual. Nota pendente muda sozinha; consulte de novo ou use webhooks.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: A nota. Nota.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
  "ambiente": "producao",
  "status": "autorizada",
  "origem": "api",
  "referencia_externa": "pedido-1042",
  "numero": "18",
  "chave_acesso": "41069021245723174000110000000000001826117319502647",
  "dps": {
    "id": "DPS410690224572317400011000001000000000000042",
    "serie": "1",
    "numero": "42"
  },
  "competencia": "2026-11-05",
  "municipio_emissor": "4106902",
  "prestador": {
    "cnpj": "45723174000110",
    "inscricao_municipal": "1234567",
    "simples_nacional": "me_epp",
    "apuracao_simples": "tudo_pelo_simples"
  },
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda",
    "inscricao_municipal": null,
    "endereco": {
      "municipio": "4106902",
      "cep": "80020310",
      "logradouro": "Rua XV de Novembro",
      "numero": "1000",
      "complemento": null,
      "bairro": "Centro"
    },
    "telefone": null,
    "email": "[email protected]"
  },
  "intermediario": null,
  "servico": {
    "codigo_tributacao_nacional": "010801",
    "codigo_nbs": null,
    "descricao": "Manutenção do site, novembro de 2026",
    "municipio_prestacao": "4106902"
  },
  "valores": {
    "valor_servico": "1500.00",
    "retencao_iss": "nao_retido",
    "aliquota_iss": null,
    "percentual_tributos_simples": "6.00"
  },
  "pendencia": null,
  "rejeicao": null,
  "cancelamento": null,
  "emails": [
    {
      "destinatario": "tomador",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-05T14:03:20-03:00"
    },
    {
      "destinatario": "emissor",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-05T14:03:20-03:00"
    }
  ],
  "links": {
    "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
    "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf",
    "consulta_publica": "https://www.nfse.gov.br/consultapublica"
  },
  "recorrencia_id": null,
  "gatilho_id": null,
  "criada_em": "2026-11-05T14:03:09-03:00",
  "autorizada_em": "2026-11-05T14:03:12-03:00",
  "atualizada_em": "2026-11-05T14:03:20-03:00"
}

Cancelar nota

POST/notas/{id}/cancelar

Escopo: notas:cancelar.

Contrato provisório até o mapeamento do Anexo II da SEFIN (leiaute do evento de cancelamento): codigo_motivo e os limites de motivo podem mudar antes da abertura.

Pede à SEFIN o cancelamento de uma nota autorizada. Cada nota tem no máximo um pedido de cancelamento em andamento, com identidade própria (cancelamento.id), gravada antes do envio do evento. Repetir o pedido, ou pedir ao mesmo tempo com outra Idempotency-Key, enquanto cancelamento.status é pendente devolve esse mesmo pedido (202), sem enviar outro evento e sem trocar o motivo. Depois de concluído, repetir devolve a nota cancelada (200), sem novo evento. Se a SEFIN recusar (422), a nota continua autorizada e um novo pedido pode ser feito. O tomador e o emissor recebem e-mail avisando, se o envio de e-mail estiver ligado.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/cancelar' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "codigo_motivo": "erro_na_emissao",
  "motivo": "Valor do serviço informado errado, nota será emitida de novo."
}'

Respostas

• 200: Nota cancelada. Nota.
• 202: A SEFIN não respondeu a tempo. cancelamento.status fica pendente e o NFSeIA confirma sozinho. Nota.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 422: A SEFIN recusou o cancelamento. A nota continua autorizada. Códigos: cancelamento_recusado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
  "ambiente": "producao",
  "status": "cancelada",
  "origem": "api",
  "referencia_externa": "pedido-1042",
  "numero": "18",
  "chave_acesso": "41069021245723174000110000000000001826117319502647",
  "dps": {
    "id": "DPS410690224572317400011000001000000000000042",
    "serie": "1",
    "numero": "42"
  },
  "competencia": "2026-11-05",
  "municipio_emissor": "4106902",
  "prestador": {
    "cnpj": "45723174000110",
    "inscricao_municipal": "1234567",
    "simples_nacional": "me_epp",
    "apuracao_simples": "tudo_pelo_simples"
  },
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda",
    "inscricao_municipal": null,
    "endereco": null,
    "telefone": null,
    "email": "[email protected]"
  },
  "intermediario": null,
  "servico": {
    "codigo_tributacao_nacional": "010801",
    "codigo_nbs": null,
    "descricao": "Manutenção do site, novembro de 2026",
    "municipio_prestacao": "4106902"
  },
  "valores": {
    "valor_servico": "1500.00",
    "retencao_iss": "nao_retido",
    "aliquota_iss": null,
    "percentual_tributos_simples": "6.00"
  },
  "pendencia": null,
  "rejeicao": null,
  "cancelamento": {
    "id": "canc_01JC99V8X1Z4B7D0F3H6K9M2P5",
    "status": "concluido",
    "codigo_motivo": "erro_na_emissao",
    "motivo": "Valor do serviço informado errado, nota será emitida de novo.",
    "solicitado_em": "2026-11-06T09:12:40-03:00",
    "concluido_em": "2026-11-06T09:12:43-03:00",
    "erros": []
  },
  "emails": [
    {
      "destinatario": "tomador",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-06T09:12:50-03:00"
    },
    {
      "destinatario": "emissor",
      "endereco": "[email protected]",
      "status": "enviado",
      "enviado_em": "2026-11-06T09:12:50-03:00"
    }
  ],
  "links": {
    "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
    "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf",
    "consulta_publica": "https://www.nfse.gov.br/consultapublica"
  },
  "recorrencia_id": null,
  "gatilho_id": null,
  "criada_em": "2026-11-05T14:03:09-03:00",
  "autorizada_em": "2026-11-05T14:03:12-03:00",
  "atualizada_em": "2026-11-06T09:12:50-03:00"
}

Baixar o XML

GET/notas/{id}/xml

Escopo: notas:ler.

XML oficial da NFS-e, como a SEFIN autorizou, guardado por 5 anos. Disponível para nota autorizada ou cancelada.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -o nota.xml

Respostas

• 200: O XML da NFS-e.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Baixar o PDF

GET/notas/{id}/pdf

Escopo: notas:ler.

Documento auxiliar da nota (DANFSe) em PDF, gerado pelo NFSeIA. No ambiente de teste, sai com a marca "sem valor fiscal". Disponível para nota autorizada ou cancelada (com a marca "cancelada").

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -o nota.pdf

Respostas

• 200: O PDF.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Reenviar a nota por e-mail

POST/notas/{id}/reenviar-email

Escopo: notas:enviar_email.

Envia de novo o e-mail da nota, com PDF, XML e o link da consulta pública. Sem corpo, vai para o tomador e para o emissor. No ambiente de teste, vai só para o e-mail do emissor, nunca para o tomador. A permissão é própria (notas:enviar_email), separada da de emissão. Pelo MCP, o envio vai só para os e-mails do cadastro do tomador e do emissor; endereço novo pede aprovação humana.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/reenviar-email' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "destinatarios": [
    "[email protected]"
  ]
}'

Respostas

• 202: Envio agendado. O resultado aparece em emails na nota.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 202:

{
  "nota_id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
  "destinatarios": [
    "[email protected]"
  ],
  "agendado_em": "2026-11-06T10:01:00-03:00"
}

Recorrências

Nota que sai sozinha todo mês para o mesmo tomador. A referência de cada nota é recorrencia:{id}:{AAAA-MM}, então cada mês gera no máximo uma nota.

Cada mês vira uma ocorrência, reservada no começo do dia da emissão (0h, horário de Brasília). A reserva congela a competência, a referência e os dados da nota (tomador, serviço e valores, já com os padrões da empresa aplicados); toda nova tentativa daquele mês usa exatamente a ocorrência congelada. Editar, pausar ou encerrar a recorrência vale para as ocorrências ainda não reservadas e não muda a que já foi reservada; para desfazer uma nota que saiu, cancele a nota.

No MVP, recorrência não aceita intermediário nem retido_pelo_intermediario.

Criar recorrência

POST/recorrencias

Escopo: recorrencias:escrever. Exige Idempotency-Key.

Configura uma nota que sai sozinha todo mês, no dia_do_mes, pela manhã (horário de Brasília). Nos meses mais curtos, sai no último dia. O emissor recebe e-mail aviso_antes_dias antes e outro quando a nota sai.

A descrição aceita {mes} e {ano}, trocados pelo mês por extenso e pelo ano da competência. A ocorrência de cada mês é reservada às 0h do dia da emissão e congela competência, referência e dados (veja Recorrências); se a nota do mês não puder sair (cota, certificado, pagamento), o NFSeIA tenta de novo a mesma ocorrência uma vez por dia por 3 dias e avisa por e-mail.

A Idempotency-Key é obrigatória e é a identidade da criação: repetir com a mesma chave devolve a mesma recorrência, nunca uma segunda. Intermediário e retido_pelo_intermediario são recusados no MVP.

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/recorrencias' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tomador": {
    "documento": "12345678000195"
  },
  "servico": {
    "descricao": "Manutenção do site, {mes} de {ano}"
  },
  "valores": {
    "valor_servico": "1500.00"
  },
  "dia_do_mes": 5,
  "inicio": "2026-12"
}'

Respostas

• 201: Recorrência criada. Recorrência.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 409: A mesma Idempotency-Key está em uso por outra requisição ou veio com outro corpo. Códigos: idempotencia_em_andamento, idempotencia_reutilizada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 201:

{
  "id": "rec_01JC90B7W2D5F8H1K4M6P9R3T5",
  "ambiente": "producao",
  "status": "ativa",
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda"
  },
  "servico": {
    "descricao": "Manutenção do site, {mes} de {ano}"
  },
  "valores": {
    "valor_servico": "1500.00"
  },
  "dia_do_mes": 5,
  "inicio": "2026-12",
  "fim": null,
  "aviso_antes_dias": 3,
  "enviar_email": null,
  "proxima_emissao": "2026-12-05",
  "ultima_nota": null,
  "criada_em": "2026-11-05T15:20:00-03:00",
  "atualizada_em": "2026-11-05T15:20:00-03:00"
}

Listar recorrências

GET/recorrencias

Escopo: recorrencias:ler.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/recorrencias?tomador_documento=12345678000195' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Página de recorrências. Lista de Recorrência em dados, com proximo_cursor.
• 400: Requisição malformada. Códigos: requisicao_invalida.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "rec_01JC90B7W2D5F8H1K4M6P9R3T5",
      "ambiente": "producao",
      "status": "ativa",
      "tomador": {
        "documento": "12345678000195",
        "nome": "Padaria Pão Quente Ltda"
      },
      "servico": {
        "descricao": "Manutenção do site, {mes} de {ano}"
      },
      "valores": {
        "valor_servico": "1500.00"
      },
      "dia_do_mes": 5,
      "inicio": "2026-12",
      "fim": null,
      "aviso_antes_dias": 3,
      "enviar_email": null,
      "proxima_emissao": "2026-12-05",
      "ultima_nota": null,
      "criada_em": "2026-11-05T15:20:00-03:00",
      "atualizada_em": "2026-11-05T15:20:00-03:00"
    }
  ],
  "proximo_cursor": null
}

Consultar recorrência

GET/recorrencias/{id}

Escopo: recorrencias:ler.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/recorrencias/rec_01JC90B7W2D5F8H1K4M6P9R3T5' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: A recorrência. Recorrência.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "rec_01JC90B7W2D5F8H1K4M6P9R3T5",
  "ambiente": "producao",
  "status": "ativa",
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda"
  },
  "servico": {
    "descricao": "Manutenção do site, {mes} de {ano}"
  },
  "valores": {
    "valor_servico": "1500.00"
  },
  "dia_do_mes": 5,
  "inicio": "2026-12",
  "fim": null,
  "aviso_antes_dias": 3,
  "enviar_email": null,
  "proxima_emissao": "2026-12-05",
  "ultima_nota": null,
  "criada_em": "2026-11-05T15:20:00-03:00",
  "atualizada_em": "2026-11-05T15:20:00-03:00"
}

Editar, pausar ou retomar

PATCH/recorrencias/{id}

Escopo: recorrencias:escrever.

Mude só o que enviar. status: pausada para de emitir; status: ativa retoma no próximo dia_do_mes. Meses pausados não são emitidos depois. A mudança vale para as ocorrências ainda não reservadas: a do mês já reservada (ocorrencia_reservada) sai com os dados congelados, e as notas já emitidas não mudam.

Parâmetros

Corpo

Exemplo

curl -X PATCH 'https://api.nfseia.com.br/v1/recorrencias/rec_01JC90B7W2D5F8H1K4M6P9R3T5' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "pausada"
}'

Outro corpo: reajustar o valor.

{
  "valores": {
    "valor_servico": "1650.00"
  }
}

Respostas

• 200: Recorrência atualizada. Recorrência.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "rec_01JC90B7W2D5F8H1K4M6P9R3T5",
  "ambiente": "producao",
  "status": "pausada",
  "tomador": {
    "documento": "12345678000195",
    "nome": "Padaria Pão Quente Ltda"
  },
  "servico": {
    "descricao": "Manutenção do site, {mes} de {ano}"
  },
  "valores": {
    "valor_servico": "1500.00"
  },
  "dia_do_mes": 5,
  "inicio": "2026-12",
  "fim": null,
  "aviso_antes_dias": 3,
  "enviar_email": null,
  "proxima_emissao": null,
  "ultima_nota": null,
  "criada_em": "2026-11-05T15:20:00-03:00",
  "atualizada_em": "2026-11-06T08:00:00-03:00"
}

Encerrar recorrência

DELETE/recorrencias/{id}

Escopo: recorrencias:escrever.

Encerra de vez; nenhuma ocorrência nova é reservada. A ocorrência já reservada, se houver, segue até o fim, e as notas já emitidas continuam valendo.

Parâmetros

Exemplo

curl -X DELETE 'https://api.nfseia.com.br/v1/recorrencias/rec_01JC90B7W2D5F8H1K4M6P9R3T5' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 204: Recorrência encerrada.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Tomadores

Clientes salvos da empresa. Com o CNPJ, a consulta pública preenche nome e endereço.

Salvar tomador

POST/tomadores

Escopo: tomadores:escrever. Exige Idempotency-Key.

Salva um cliente. Com CNPJ e sem nome, a consulta pública preenche nome e endereço (origem_dos_dados: consulta_publica); com CPF, o nome é obrigatório. O documento é único por empresa e ambiente: salvar de novo um documento existente devolve o tomador salvo (200, com NFSeIA-Recurso-Existente: true); para mudar, use PATCH.

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/tomadores' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "documento": "12345678000195",
  "email": "[email protected]"
}'

Outro corpo: pessoa física.

{
  "documento": "529.982.247-25",
  "nome": "Marina Souza",
  "email": "[email protected]"
}

Respostas

• 200: O documento já estava salvo. Volta o tomador existente, sem mudança. Tomador.
• 201: Tomador salvo. Tomador.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 409: A mesma Idempotency-Key está em uso por outra requisição ou veio com outro corpo. Códigos: idempotencia_em_andamento, idempotencia_reutilizada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9",
  "ambiente": "producao",
  "documento": "12345678000195",
  "nome": "Padaria Pão Quente Ltda",
  "inscricao_municipal": null,
  "endereco": {
    "municipio": "4106902",
    "cep": "80020310",
    "logradouro": "Rua XV de Novembro",
    "numero": "1000",
    "complemento": null,
    "bairro": "Centro"
  },
  "telefone": null,
  "email": "[email protected]",
  "enviar_email": true,
  "origem_dos_dados": "consulta_publica",
  "criado_em": "2026-11-02T10:15:00-03:00",
  "atualizado_em": "2026-11-02T10:15:00-03:00"
}

Listar e buscar tomadores

GET/tomadores

Escopo: tomadores:ler.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/tomadores?busca=padaria' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Página de tomadores. Lista de Tomador em dados, com proximo_cursor.
• 400: Requisição malformada. Códigos: requisicao_invalida.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9",
      "ambiente": "producao",
      "documento": "12345678000195",
      "nome": "Padaria Pão Quente Ltda",
      "inscricao_municipal": null,
      "endereco": {
        "municipio": "4106902",
        "cep": "80020310",
        "logradouro": "Rua XV de Novembro",
        "numero": "1000",
        "complemento": null,
        "bairro": "Centro"
      },
      "telefone": null,
      "email": "[email protected]",
      "enviar_email": true,
      "origem_dos_dados": "consulta_publica",
      "criado_em": "2026-11-02T10:15:00-03:00",
      "atualizado_em": "2026-11-02T10:15:00-03:00"
    }
  ],
  "proximo_cursor": null
}

Consultar tomador

GET/tomadores/{id}

Escopo: tomadores:ler.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/tomadores/tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: O tomador. Tomador.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9",
  "ambiente": "producao",
  "documento": "12345678000195",
  "nome": "Padaria Pão Quente Ltda",
  "inscricao_municipal": null,
  "endereco": {
    "municipio": "4106902",
    "cep": "80020310",
    "logradouro": "Rua XV de Novembro",
    "numero": "1000",
    "complemento": null,
    "bairro": "Centro"
  },
  "telefone": null,
  "email": "[email protected]",
  "enviar_email": true,
  "origem_dos_dados": "consulta_publica",
  "criado_em": "2026-11-02T10:15:00-03:00",
  "atualizado_em": "2026-11-02T10:15:00-03:00"
}

Editar tomador

PATCH/tomadores/{id}

Escopo: tomadores:escrever.

Mude só o que enviar. O documento não muda; para outro documento, salve outro tomador.

Parâmetros

Corpo

Exemplo

curl -X PATCH 'https://api.nfseia.com.br/v1/tomadores/tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "enviar_email": false
}'

Respostas

• 200: Tomador atualizado. Tomador.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9",
  "ambiente": "producao",
  "documento": "12345678000195",
  "nome": "Padaria Pão Quente Ltda",
  "inscricao_municipal": null,
  "endereco": {
    "municipio": "4106902",
    "cep": "80020310",
    "logradouro": "Rua XV de Novembro",
    "numero": "1000",
    "complemento": null,
    "bairro": "Centro"
  },
  "telefone": null,
  "email": "[email protected]",
  "enviar_email": true,
  "origem_dos_dados": "consulta_publica",
  "criado_em": "2026-11-02T10:15:00-03:00",
  "atualizado_em": "2026-11-02T10:15:00-03:00"
}

Excluir tomador

DELETE/tomadores/{id}

Escopo: tomadores:escrever.

Remove o cadastro. Notas já emitidas guardam os dados do tomador como estavam.

Parâmetros

Exemplo

curl -X DELETE 'https://api.nfseia.com.br/v1/tomadores/tom_01JC8YQ2N5R8T1W4Y7A0C3E6G9' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 204: Tomador excluído.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Consultas

Consulta pública de CNPJ e busca do código de serviço.

Consultar CNPJ

GET/consultas/cnpj/{cnpj}

Escopo: tomadores:ler.

Dados públicos do CNPJ (razão social, endereço, situação cadastral e Simples Nacional), sem salvar nada. Útil para conferir o cliente antes de salvar ou emitir.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/consultas/cnpj/12345678000195' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Dados públicos do CNPJ.
• 400: Requisição malformada. Códigos: requisicao_invalida.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.
• 503: Serviço fora do ar por alguns instantes. Códigos: indisponivel.

Exemplo de resposta 200:

{
  "cnpj": "12345678000195",
  "razao_social": "Padaria Pão Quente Ltda",
  "nome_fantasia": "Pão Quente",
  "situacao_cadastral": "ativa",
  "endereco": {
    "municipio": "4106902",
    "cep": "80020310",
    "logradouro": "Rua XV de Novembro",
    "numero": "1000",
    "complemento": null,
    "bairro": "Centro"
  },
  "simples_nacional": {
    "optante": true,
    "mei": false
  },
  "consultado_em": "2026-11-05T14:00:02-03:00"
}

Buscar código de serviço

GET/codigos-servico

Qualquer chave.

Busca na lista nacional de serviços por palavra. A resposta sugere; a escolha do código é da empresa e do contador dela, e o NFSeIA não decide enquadramento fiscal.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/codigos-servico?busca=manuten%C3%A7%C3%A3o%20de%20site' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Códigos encontrados, do mais parecido para o menos.
• 400: Requisição malformada. Códigos: requisicao_invalida.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "codigo_tributacao_nacional": "010801",
      "item_lista": "01.08",
      "descricao": "Planejamento, confecção, manutenção e atualização de páginas eletrônicas."
    },
    {
      "codigo_tributacao_nacional": "010701",
      "item_lista": "01.07",
      "descricao": "Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."
    }
  ],
  "aviso": "A escolha do código de serviço é da sua empresa e do seu contador. Confirme antes de emitir."
}

Gatilhos

Emissão automática ao receber pagamento ("recebeu, emitiu"). Cada gatilho tem um endereço de entrada que recebe o aviso de pagamento, assinado com o segredo do gatilho, e emite a nota a partir de um modelo.

A identidade da nota é pagamento:{provedor}:{conta}:{pagamento_id}, com provedor e conta vindos da configuração do gatilho (origem). Gatilhos com o mesmo provedor e a mesma conta compartilham a identidade: o mesmo pagamento nunca gera duas notas, mesmo que chegue por dois deles. O prefixo pagamento: é reservado e recusado na emissão manual (POST /notas).

No MVP, gatilho não aceita intermediário nem retido_pelo_intermediario.

Criar gatilho de pagamento

POST/gatilhos

Escopo: gatilhos:gerenciar. Exige Idempotency-Key.

Cria um endereço de entrada para avisos de pagamento. A resposta traz o segredo uma única vez: guarde no seu sistema, ele assina cada aviso.

origem.provedor e origem.conta identificam de onde vêm os pagamentos (por exemplo o seu sistema de cobrança e a conta nele) e entram na identidade da nota, pagamento:{provedor}:{conta}:{pagamento_id}. Gatilhos com a mesma origem compartilham essa identidade.

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/gatilhos' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "nome": "Assinaturas do sistema",
  "origem": {
    "provedor": "meu-sistema",
    "conta": "principal"
  },
  "modelo": {
    "usar_valor_do_aviso": true,
    "tomador": null,
    "servico": {
      "descricao": "Assinatura mensal do sistema de gestão"
    },
    "valores": {}
  }
}'

Respostas

• 201: Gatilho criado, com o segredo (só nesta resposta). Gatilho, com segredo.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 409: A mesma Idempotency-Key está em uso por outra requisição ou veio com outro corpo. Códigos: idempotencia_em_andamento, idempotencia_reutilizada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 201:

{
  "id": "gat_01JC91D3F6H9K2M5P8R1T4W7Y0",
  "ambiente": "producao",
  "nome": "Assinaturas do sistema",
  "origem": {
    "provedor": "meu-sistema",
    "conta": "principal"
  },
  "status": "ativo",
  "url": "https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/eventos",
  "segredo": "gsec_6fQ2xN8vR1kT4mW7zB0cE3hJ5",
  "modelo": {
    "usar_valor_do_aviso": true,
    "tomador": null,
    "servico": {
      "descricao": "Assinatura mensal do sistema de gestão"
    },
    "valores": {}
  },
  "ultimo_evento_em": null,
  "criado_em": "2026-11-05T16:00:00-03:00",
  "atualizado_em": "2026-11-05T16:00:00-03:00"
}

Listar gatilhos

GET/gatilhos

Escopo: gatilhos:gerenciar.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/gatilhos' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Página de gatilhos (sem os segredos). Lista de Gatilho em dados, com proximo_cursor.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "gat_01JC91D3F6H9K2M5P8R1T4W7Y0",
      "ambiente": "producao",
      "nome": "Assinaturas do sistema",
      "origem": {
        "provedor": "meu-sistema",
        "conta": "principal"
      },
      "status": "ativo",
      "url": "https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/eventos",
      "modelo": {
        "usar_valor_do_aviso": true,
        "tomador": null,
        "servico": {
          "descricao": "Assinatura mensal do sistema de gestão"
        },
        "valores": {}
      },
      "ultimo_evento_em": "2026-11-05T16:42:10-03:00",
      "criado_em": "2026-11-05T16:00:00-03:00",
      "atualizado_em": "2026-11-05T16:00:00-03:00"
    }
  ],
  "proximo_cursor": null
}

Consultar gatilho

GET/gatilhos/{id}

Escopo: gatilhos:gerenciar.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: O gatilho (sem o segredo). Gatilho.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "gat_01JC91D3F6H9K2M5P8R1T4W7Y0",
  "ambiente": "producao",
  "nome": "Assinaturas do sistema",
  "origem": {
    "provedor": "meu-sistema",
    "conta": "principal"
  },
  "status": "ativo",
  "url": "https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/eventos",
  "modelo": {
    "usar_valor_do_aviso": true,
    "tomador": null,
    "servico": {
      "descricao": "Assinatura mensal do sistema de gestão"
    },
    "valores": {}
  },
  "ultimo_evento_em": "2026-11-05T16:42:10-03:00",
  "criado_em": "2026-11-05T16:00:00-03:00",
  "atualizado_em": "2026-11-05T16:00:00-03:00"
}

Editar ou pausar gatilho

PATCH/gatilhos/{id}

Escopo: gatilhos:gerenciar.

Mude só o que enviar. Gatilho pausado responde 409 estado_invalido aos avisos, e eles podem ser reenviados depois. A origem não muda depois da criação: mudar a identidade dos pagamentos abriria espaço para nota em dobro.

Parâmetros

Corpo

Exemplo

curl -X PATCH 'https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "pausado"
}'

Respostas

• 200: Gatilho atualizado. Gatilho.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "gat_01JC91D3F6H9K2M5P8R1T4W7Y0",
  "ambiente": "producao",
  "nome": "Assinaturas do sistema",
  "origem": {
    "provedor": "meu-sistema",
    "conta": "principal"
  },
  "status": "pausado",
  "url": "https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/eventos",
  "modelo": {
    "usar_valor_do_aviso": true,
    "tomador": null,
    "servico": {
      "descricao": "Assinatura mensal do sistema de gestão"
    },
    "valores": {}
  },
  "ultimo_evento_em": "2026-11-05T16:42:10-03:00",
  "criado_em": "2026-11-05T16:00:00-03:00",
  "atualizado_em": "2026-11-06T08:00:00-03:00"
}

Excluir gatilho

DELETE/gatilhos/{id}

Escopo: gatilhos:gerenciar.

O endereço para de aceitar avisos na hora. Notas já emitidas não mudam.

Parâmetros

Exemplo

curl -X DELETE 'https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 204: Gatilho excluído.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Trocar o segredo do gatilho

POST/gatilhos/{id}/rotacionar-segredo

Escopo: gatilhos:gerenciar. Exige Idempotency-Key.

Gera um segredo novo, em um de dois modos:

• normal: o segredo anterior continua aceito por 24 horas, para dar tempo de trocar no seu sistema. No máximo um anterior fica valendo: uma nova troca normal revoga o mais antigo na hora.
• emergencia: revoga todos os anteriores na hora, sem sobreposição. Use se o segredo vazou.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/rotacionar-segredo' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "modo": "normal"
}'

Respostas

• 200: Segredo novo (só nesta resposta).
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "segredo": "gsec_9aL4pR7sV0xY3bD6fH8jK1mN2",
  "anterior_valido_ate": "2026-11-07T11:30:00-03:00"
}

Receber aviso de pagamento

POST/gatilhos/{id}/eventos

Endereço público: sem chave de API, só com NFSeIA-Assinatura.

Endereço público do gatilho: o seu sistema avisa que um pagamento foi confirmado e a nota sai pelo modelo do gatilho. Não usa chave de API; o aviso vale só com NFSeIA-Assinatura calculada com o segredo do gatilho sobre o corpo bruto, como nos webhooks.

A identidade da nota é pagamento:{provedor}:{conta}:{pagamento_id}, com provedor e conta da origem do gatilho; ela é reservada antes de qualquer envio, como na emissão. Repetir o aviso do mesmo pagamento, por este ou por outro gatilho da mesma origem, devolve a nota existente (200), nunca uma segunda. Valor e tomador passam pela mesma validação da emissão; intermediário e retido_pelo_intermediario são recusados no MVP.

Proteções: o carimbo de tempo t precisa estar a até 5 minutos do horário atual, no passado ou no futuro (assine cada envio na hora, com t novo a cada tentativa); o limite por IP vale antes de conferir a assinatura, inclusive para assinatura inválida, e o limite por gatilho e por empresa vale depois.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/gatilhos/gat_01JC91D3F6H9K2M5P8R1T4W7Y0/eventos' \
  -H "NFSeIA-Assinatura: t=$T,v1=$ASSINATURA" \
  -H "Content-Type: application/json" \
  -d '{
  "pagamento_id": "fatura-2026-11-0087",
  "valor": "89.90",
  "pago_em": "2026-11-05T16:42:07-03:00",
  "tomador": {
    "documento": "33445566000186",
    "nome": "Clínica Bem Viver Ltda",
    "email": "[email protected]"
  }
}'

Respostas

• 200: Este pagamento já tinha nota. Volta a nota existente. Nota.
• 201: Nota autorizada. Nota.
• 202: A SEFIN não respondeu a tempo; a nota fica pendente. Nota.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Aviso de pagamento sem assinatura válida. Códigos: assinatura_invalida.
• 402: Teste grátis encerrado, cota do mês esgotada ou assinatura em atraso. Códigos: cota_esgotada.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 409: A operação não cabe no estado atual do recurso. Códigos: estado_invalido.
• 422: A SEFIN recusou a nota. Ela fica guardada como rejeitada, com o id em nota_id. Códigos: nota_rejeitada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "nota_01JC92F5H8K1M4P7R0T3W6Y9A2",
  "ambiente": "producao",
  "status": "autorizada",
  "origem": "gatilho",
  "referencia_externa": "pagamento:meu-sistema:principal:fatura-2026-11-0087",
  "numero": "19",
  "chave_acesso": "41069021245723174000110000000000001926118402736915",
  "dps": {
    "id": "DPS410690224572317400011000001000000000000045",
    "serie": "1",
    "numero": "45"
  },
  "competencia": "2026-11-05",
  "municipio_emissor": "4106902",
  "prestador": {
    "cnpj": "45723174000110",
    "inscricao_municipal": "1234567",
    "simples_nacional": "me_epp",
    "apuracao_simples": "tudo_pelo_simples"
  },
  "tomador": {
    "documento": "33445566000186",
    "nome": "Clínica Bem Viver Ltda",
    "inscricao_municipal": null,
    "endereco": null,
    "telefone": null,
    "email": "[email protected]"
  },
  "intermediario": null,
  "servico": {
    "codigo_tributacao_nacional": "010801",
    "codigo_nbs": null,
    "descricao": "Assinatura mensal do sistema de gestão",
    "municipio_prestacao": "4106902"
  },
  "valores": {
    "valor_servico": "89.90",
    "retencao_iss": "nao_retido",
    "aliquota_iss": null,
    "percentual_tributos_simples": "6.00"
  },
  "pendencia": null,
  "rejeicao": null,
  "cancelamento": null,
  "emails": [
    {
      "destinatario": "tomador",
      "endereco": "[email protected]",
      "status": "agendado",
      "enviado_em": null
    }
  ],
  "links": {
    "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC92F5H8K1M4P7R0T3W6Y9A2/xml",
    "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC92F5H8K1M4P7R0T3W6Y9A2/pdf",
    "consulta_publica": "https://www.nfse.gov.br/consultapublica"
  },
  "recorrencia_id": null,
  "gatilho_id": "gat_01JC91D3F6H9K2M5P8R1T4W7Y0",
  "criada_em": "2026-11-05T16:42:08-03:00",
  "autorizada_em": "2026-11-05T16:42:11-03:00",
  "atualizada_em": "2026-11-05T16:42:11-03:00"
}

Webhooks

Endereços do seu sistema que recebem os eventos das notas, assinados com HMAC-SHA256.

Cadastrar webhook

POST/webhooks

Escopo: webhooks:gerenciar. Exige Idempotency-Key.

Cadastra um endereço do seu sistema para receber eventos. A resposta traz o segredo uma única vez.

Só HTTPS público. O endereço é conferido no cadastro, na edição, em cada entrega e em cada reenvio: o nome é resolvido no DNS a cada envio, todos os IPs devolvidos precisam ser públicos (nada interno, privado, de rede local ou reservado) e a conexão vai para o IP aprovado nessa conferência. Redirecionamento não é seguido. Cada tentativa tem até 10 segundos e lê no máximo 64 KB da resposta.

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/webhooks' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://meusistema.com.br/avisos/nfseia",
  "eventos": [
    "nota.autorizada",
    "nota.rejeitada",
    "nota.pendente_resolvida",
    "nota.cancelada"
  ],
  "descricao": "Atualiza o pedido quando a nota sai"
}'

Respostas

• 201: Webhook cadastrado, com o segredo (só nesta resposta). Webhook, com segredo.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 409: A mesma Idempotency-Key está em uso por outra requisição ou veio com outro corpo. Códigos: idempotencia_em_andamento, idempotencia_reutilizada.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 201:

{
  "id": "wh_01JC93H7K0M3P6R9T2W5Y8A1C4",
  "ambiente": "producao",
  "url": "https://meusistema.com.br/avisos/nfseia",
  "eventos": [
    "nota.autorizada",
    "nota.rejeitada",
    "nota.pendente_resolvida",
    "nota.cancelada"
  ],
  "descricao": "Atualiza o pedido quando a nota sai",
  "status": "ativo",
  "segredo": "whsec_3kD8nQ1rT6vX9zB2eG5hL7pS0",
  "criado_em": "2026-11-05T17:00:00-03:00",
  "atualizado_em": "2026-11-05T17:00:00-03:00"
}

Listar webhooks

GET/webhooks

Escopo: webhooks:gerenciar.

Exemplo

curl 'https://api.nfseia.com.br/v1/webhooks' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Webhooks do ambiente (sem os segredos). Lista de Webhook em dados, com proximo_cursor.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "wh_01JC93H7K0M3P6R9T2W5Y8A1C4",
      "ambiente": "producao",
      "url": "https://meusistema.com.br/avisos/nfseia",
      "eventos": [
        "nota.autorizada",
        "nota.rejeitada",
        "nota.pendente_resolvida",
        "nota.cancelada"
      ],
      "descricao": "Atualiza o pedido quando a nota sai",
      "status": "ativo",
      "criado_em": "2026-11-05T17:00:00-03:00",
      "atualizado_em": "2026-11-05T17:00:00-03:00"
    }
  ],
  "proximo_cursor": null
}

Consultar webhook

GET/webhooks/{id}

Escopo: webhooks:gerenciar.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: O webhook (sem o segredo). Webhook.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "wh_01JC93H7K0M3P6R9T2W5Y8A1C4",
  "ambiente": "producao",
  "url": "https://meusistema.com.br/avisos/nfseia",
  "eventos": [
    "nota.autorizada"
  ],
  "descricao": "Atualiza o pedido quando a nota sai",
  "status": "ativo",
  "criado_em": "2026-11-05T17:00:00-03:00",
  "atualizado_em": "2026-11-05T17:00:00-03:00"
}

Editar, pausar ou reativar webhook

PATCH/webhooks/{id}

Escopo: webhooks:gerenciar.

Mude só o que enviar. Um url novo passa pela mesma conferência do cadastro. Reativar um webhook desativado volta a entregar só os eventos novos.

Parâmetros

Corpo

Exemplo

curl -X PATCH 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "eventos": [
    "nota.autorizada",
    "nota.rejeitada",
    "nota.pendente_resolvida",
    "nota.cancelada",
    "nota_recorrente.emitida"
  ]
}'

Respostas

• 200: Webhook atualizado. Webhook.
• 400: Dados recusados antes de qualquer envio à SEFIN (dados_invalidos), JSON malformado (requisicao_invalida) ou POST sem Idempotency-Key (idempotency_key_ausente). Nada foi criado. Códigos: dados_invalidos, idempotency_key_ausente.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "wh_01JC93H7K0M3P6R9T2W5Y8A1C4",
  "ambiente": "producao",
  "url": "https://meusistema.com.br/avisos/nfseia",
  "eventos": [
    "nota.autorizada",
    "nota.rejeitada",
    "nota.pendente_resolvida",
    "nota.cancelada",
    "nota_recorrente.emitida"
  ],
  "descricao": "Atualiza o pedido quando a nota sai",
  "status": "ativo",
  "criado_em": "2026-11-05T17:00:00-03:00",
  "atualizado_em": "2026-11-06T08:00:00-03:00"
}

Excluir webhook

DELETE/webhooks/{id}

Escopo: webhooks:gerenciar.

Parâmetros

Exemplo

curl -X DELETE 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 204: Webhook excluído; entregas pendentes são descartadas.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Trocar o segredo do webhook

POST/webhooks/{id}/rotacionar-segredo

Escopo: webhooks:gerenciar. Exige Idempotency-Key.

Gera um segredo novo, em um de dois modos:

• normal: por 24 horas, cada entrega leva duas assinaturas em NFSeIA-Assinatura (v1 com o segredo novo e v1 com o anterior); aceite qualquer uma que confira. No máximo um anterior fica valendo: uma nova troca normal revoga o mais antigo na hora.
• emergencia: revoga todos os anteriores na hora; as entregas passam a levar só o v1 do segredo novo. Use se o segredo vazou.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4/rotacionar-segredo' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "modo": "emergencia"
}'

Respostas

• 200: Segredo novo (só nesta resposta).
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "segredo": "whsec_8tF1mK4qW7zC0eH3jN6rV9yB2",
  "anterior_valido_ate": null
}

Listar entregas

GET/webhooks/{id}/entregas

Escopo: webhooks:gerenciar.

Histórico de entregas do webhook nos últimos 30 dias, da mais nova para a mais antiga.

Parâmetros

Exemplo

curl 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4/entregas' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: Página de entregas. Lista de Entrega em dados, com proximo_cursor.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "dados": [
    {
      "id": "ent_01JC94K9M2P5R8T1W4Y7A0C3E6",
      "evento_id": "evt_01JC8Z4P6R9T2W5Y8A1C4E7G0J",
      "tipo": "nota.autorizada",
      "status": "tentando",
      "tentativas": 2,
      "ultima_tentativa": {
        "em": "2026-11-05T14:04:15-03:00",
        "http_status": 503,
        "duracao_ms": 412,
        "erro": null
      },
      "proxima_tentativa_em": "2026-11-05T14:34:15-03:00",
      "criada_em": "2026-11-05T14:03:12-03:00"
    }
  ],
  "proximo_cursor": null
}

Reenviar entrega

POST/webhooks/{id}/entregas/{entrega_id}/reenviar

Escopo: webhooks:gerenciar.

Tenta entregar o evento de novo, agora, com a mesma conferência de endereço de uma entrega normal e um carimbo de tempo novo na assinatura. O id do evento é o mesmo, para o seu sistema descartar repetidos.

Parâmetros

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/webhooks/wh_01JC93H7K0M3P6R9T2W5Y8A1C4/entregas/ent_01JC94K9M2P5R8T1W4Y7A0C3E6/reenviar' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 202: Reenvio agendado. Entrega.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 404: Não existe, é de outra empresa ou de outro ambiente. Códigos: nao_encontrado.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 202:

{
  "id": "ent_01JC94K9M2P5R8T1W4Y7A0C3E6",
  "evento_id": "evt_01JC8Z4P6R9T2W5Y8A1C4E7G0J",
  "tipo": "nota.autorizada",
  "status": "tentando",
  "tentativas": 2,
  "ultima_tentativa": {
    "em": "2026-11-05T14:04:15-03:00",
    "http_status": 503,
    "duracao_ms": 412,
    "erro": null
  },
  "proxima_tentativa_em": "2026-11-05T14:10:00-03:00",
  "criada_em": "2026-11-05T14:03:12-03:00"
}

Empresa

Dados da empresa da chave, plano, cota e certificado digital (só os metadados).

O certificado nunca passa por esta API. Para enviar ou trocar, gere um link de envio (POST /empresa/certificado/link-de-envio ou no painel): ele abre o cofre, em outro endereço (cofre.nfseia.com.br), e o arquivo e a senha vão direto para lá. A troca só vale depois da confirmação pelo link enviado ao e-mail da empresa.

Consultar empresa

GET/empresa

Escopo: empresa:ler.

Dados da empresa da chave, padrões da nota, plano, cota usada, limites e certificado digital. Do certificado, só metadados (titular, CNPJ, validade); nunca o arquivo, a senha ou a chave privada.

Exemplo

curl 'https://api.nfseia.com.br/v1/empresa' \
  -H "Authorization: Bearer $NFSEIA_CHAVE"

Respostas

• 200: A empresa. Empresa.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 200:

{
  "id": "emp_01JC8V2B5D8F1H4K7M0P3R6T9W",
  "cnpj": "45723174000110",
  "razao_social": "Estúdio Aurora Design Ltda",
  "nome_fantasia": "Estúdio Aurora",
  "inscricao_municipal": "1234567",
  "municipio": {
    "codigo_ibge": "4106902",
    "nome": "Curitiba",
    "uf": "PR"
  },
  "simples_nacional": "me_epp",
  "apuracao_simples": "tudo_pelo_simples",
  "padroes_da_nota": {
    "servico": {
      "codigo_tributacao_nacional": "010801",
      "codigo_nbs": null,
      "descricao": "Manutenção do site",
      "municipio_prestacao": "4106902"
    },
    "valores": {
      "retencao_iss": "nao_retido",
      "aliquota_iss": null,
      "percentual_tributos_simples": "6.00"
    }
  },
  "plano": {
    "nome": "essencial",
    "cota_mensal": 500,
    "periodo_inicio": "2026-11-01",
    "periodo_fim": "2026-11-30",
    "notas_usadas": 18,
    "notas_restantes": 482
  },
  "teste_gratis": null,
  "producao_liberada": true,
  "limites": {
    "notas_por_dia": 500,
    "valor_maximo_por_nota": "100000.00"
  },
  "certificado": {
    "status": "valido",
    "titular": "ESTUDIO AURORA DESIGN LTDA:45723174000110",
    "cnpj": "45723174000110",
    "valido_de": "2026-03-10",
    "valido_ate": "2027-03-10",
    "enviado_em": "2026-11-01T09:30:00-03:00"
  },
  "email": {
    "envio_ligado": true,
    "emissor": "[email protected]"
  },
  "chave": {
    "prefixo": "nfs_live_7Hq2",
    "ambiente": "producao",
    "escopos": [
      "notas:ler",
      "notas:emitir",
      "notas:enviar_email",
      "notas:cancelar",
      "empresa:ler"
    ]
  }
}

Gerar link de envio do certificado

POST/empresa/certificado/link-de-envio

Escopo: empresa:certificado. Exige Idempotency-Key.

Gera um link curto (15 minutos, uso único, amarrado à empresa) para enviar ou trocar o certificado A1 no cofre, em cofre.nfseia.com.br. O arquivo e a senha vão do navegador direto para o cofre, sem passar por esta API. O cofre confere se o certificado é e-CNPJ da própria empresa, dentro da validade e não revogado; a troca só vale depois da confirmação pelo e-mail da empresa.

Exemplo

curl -X POST 'https://api.nfseia.com.br/v1/empresa/certificado/link-de-envio' \
  -H "Authorization: Bearer $NFSEIA_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)"

Respostas

• 201: Link criado.
• 401: Chave ausente, errada, revogada ou de outro ambiente. Códigos: chave_invalida.
• 403: Falta escopo na chave, produção não liberada, certificado indisponível ou valor acima do limite. Códigos: certificado_indisponivel, sem_permissao.
• 429: Limite de requisições ou teto diário de notas. Códigos: limite_de_requisicoes.

Exemplo de resposta 201:

{
  "url": "https://cofre.nfseia.com.br/enviar#t=ct_01JC95M1P4R7T0W3Y6A9C2E5G8",
  "expira_em": "2026-11-05T17:45:00-03:00"
}

Eventos de webhook

Cada evento chega por POST no endereço cadastrado, com corpo JSON e estes cabeçalhos. Como conferir a assinatura: Webhooks.

nota.autorizada

A nota foi autorizada. Chega para toda nota autorizada, inclusive as que passaram por pendente, as recorrentes e as de gatilho.

{
  "id": "evt_01JC8Z4P6R9T2W5Y8A1C4E7G0J",
  "tipo": "nota.autorizada",
  "criado_em": "2026-11-05T14:03:12-03:00",
  "ambiente": "producao",
  "dados": {
    "nota": {
      "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
      "referencia_externa": "pedido-1042",
      "status": "autorizada",
      "numero": "18",
      "chave_acesso": "41069021245723174000110000000000001826117319502647",
      "links": {
        "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
        "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf"
      }
    }
  }
}

nota.rejeitada

A SEFIN recusou a nota. Os erros traduzidos estão na nota (GET /notas/{id}).

{
  "id": "evt_01JC96P3R6T9W2Y5A8C1E4G7J0",
  "tipo": "nota.rejeitada",
  "criado_em": "2026-11-05T14:20:31-03:00",
  "ambiente": "producao",
  "dados": {
    "nota": {
      "id": "nota_01JC8ZA1C4E7G0J3M6P9S2V5X8",
      "referencia_externa": "pedido-1050",
      "status": "rejeitada",
      "numero": null,
      "chave_acesso": null,
      "links": {
        "xml": null,
        "pdf": null
      }
    }
  }
}

nota.pendente

A nota ficou pendente; o motivo está em dados.nota.motivo_pendencia. Com aguardando_sefin ou conferindo_identidade, nada a fazer: o NFSeIA resolve sozinho. O evento chega de novo se o motivo mudar para colisao_numeracao ou requer_intervencao, que pedem atenção (o e-mail da empresa também é avisado).

{
  "id": "evt_01JC97R5T8W1Y4A7C0E3G6J9M2",
  "tipo": "nota.pendente",
  "criado_em": "2026-11-05T14:30:26-03:00",
  "ambiente": "producao",
  "dados": {
    "nota": {
      "id": "nota_01JC8ZC3E6G9J2M5P8S1V4X7Z0",
      "referencia_externa": "pedido-1051",
      "status": "pendente",
      "motivo_pendencia": "aguardando_sefin",
      "numero": null,
      "chave_acesso": null,
      "links": {
        "xml": null,
        "pdf": null
      }
    }
  }
}

nota.pendente_resolvida

A nota pendente teve resposta definitiva; dados.nota.status diz qual (autorizada ou rejeitada). O evento do status final (nota.autorizada ou nota.rejeitada) também é enviado.

{
  "id": "evt_01JC98T7W0Y3A6C9E2G5J8M1P4",
  "tipo": "nota.pendente_resolvida",
  "criado_em": "2026-11-05T14:31:02-03:00",
  "ambiente": "producao",
  "dados": {
    "nota": {
      "id": "nota_01JC8ZC3E6G9J2M5P8S1V4X7Z0",
      "referencia_externa": "pedido-1051",
      "status": "autorizada",
      "numero": "20",
      "chave_acesso": "41069021245723174000110000000000002026118264013957",
      "links": {
        "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8ZC3E6G9J2M5P8S1V4X7Z0/xml",
        "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8ZC3E6G9J2M5P8S1V4X7Z0/pdf"
      }
    }
  }
}

nota.cancelada

A nota foi cancelada na SEFIN.

{
  "id": "evt_01JC99W9Y2A5C8E1G4J7M0P3S6",
  "tipo": "nota.cancelada",
  "criado_em": "2026-11-06T09:12:44-03:00",
  "ambiente": "producao",
  "dados": {
    "nota": {
      "id": "nota_01JC8Z4M3QK7T2V9X5B6N1R0PD",
      "referencia_externa": "pedido-1042",
      "status": "cancelada",
      "numero": "18",
      "chave_acesso": "41069021245723174000110000000000001826117319502647",
      "links": {
        "xml": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/xml",
        "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JC8Z4M3QK7T2V9X5B6N1R0PD/pdf"
      }
    }
  }
}

nota_recorrente.emitida

A nota do mês de uma recorrência foi autorizada. nota.autorizada também é enviado.

{
  "id": "evt_01JCA0Y1A4C7E0G3J6M9P2S5V8",
  "tipo": "nota_recorrente.emitida",
  "criado_em": "2026-12-05T08:00:41-03:00",
  "ambiente": "producao",
  "dados": {
    "recorrencia_id": "rec_01JC90B7W2D5F8H1K4M6P9R3T5",
    "competencia": "2026-12",
    "nota": {
      "id": "nota_01JDQ3B6D9F2H5K8N1Q4S7V0X3",
      "referencia_externa": "recorrencia:rec_01JC90B7W2D5F8H1K4M6P9R3T5:2026-12",
      "status": "autorizada",
      "numero": "31",
      "chave_acesso": "41069021245723174000110000000000003126124517390826",
      "links": {
        "xml": "https://api.nfseia.com.br/v1/notas/nota_01JDQ3B6D9F2H5K8N1Q4S7V0X3/xml",
        "pdf": "https://api.nfseia.com.br/v1/notas/nota_01JDQ3B6D9F2H5K8N1Q4S7V0X3/pdf"
      }
    }
  }
}

certificado.vencendo

O certificado digital vence em 30, 15, 7 e 1 dia. Sem certificado válido, a emissão em produção para.

{
  "id": "evt_01JCA1A3C6E9G2J5M8P1S4V7Y0",
  "tipo": "certificado.vencendo",
  "criado_em": "2027-02-23T08:00:00-03:00",
  "ambiente": "producao",
  "dados": {
    "certificado": {
      "titular": "ESTUDIO AURORA DESIGN LTDA:45723174000110",
      "valido_ate": "2027-03-10",
      "dias_restantes": 15
    }
  }
}

cota.perto_do_fim

A empresa usou 80% e depois 95% da cota de notas do mês.

{
  "id": "evt_01JCA2C5E8G1J4M7P0S3V6Y9B2",
  "tipo": "cota.perto_do_fim",
  "criado_em": "2026-11-24T11:02:00-03:00",
  "ambiente": "producao",
  "dados": {
    "cota": {
      "plano": "essencial",
      "cota_mensal": 500,
      "notas_usadas": 400,
      "percentual": 80,
      "periodo_fim": "2026-11-30"
    }
  }
}

Objetos

Campos dos objetos que as operações devolvem. Datas no horário de Brasília; valores em texto com ponto e duas casas.

Objeto Nota

Objeto Recorrência

Objeto Tomador

Objeto Gatilho

Objeto Webhook

Objeto Entrega

Objeto Empresa

Objeto Erro

Só estes campos saem num erro. Nunca vão em resposta, erro ou conteúdo do MCP: o corpo bruto da SEFIN, XML de DPS ou NFS-e, credenciais, segredos, nem material de certificado. As mensagens da SEFIN chegam traduzidas, com o código em codigo_sefin.

Objeto Evento