Emitir NFS-e
Dispara o fluxo de emissão de NFS-e. Para emissão nacional, o serviço configurado deve ter código nacional de seis dígitos e, quando informado, nationalMunicipalTaxCode com exatamente três dígitos. A ausência desse campo permite o fallback do código municipal do serviço (serviceMunicipalCode) somente quando ele também tiver três dígitos; valores de outro formato não são truncados. Uma DPS que não atender ao perfil fiscal do ambiente é rejeitada antes de acessar ou assinar o certificado com a categoria SERVICE_INVOICE.NATIONAL_DPS_INVALID. Requer perfil de administrador.
Idempotência da emissão manual. O cabeçalho Idempotency-Key é opcional. Quando omitido, a API gera uma chave interna para a tentativa (compatível com clientes que não enviam o cabeçalho), mas uma repetição da requisição não é reconhecida como a mesma emissão. Para repetir com segurança após timeout ou erro de rede, envie uma chave opaca estável por tentativa e reutilize-a: - mesma chave e mesmo corpo, nota já aceita (processing/issued): 201 com a nota existente e mensagem Service invoice request already accepted., sem nova chamada ao provedor; - mesma chave e corpo diferente: 409 SERVICE_INVOICE.ISSUE_IDEMPOTENCY_MISMATCH; - mesma chave com reserva ainda pendente ou resultado incerto: 409 SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED; - chave fora do formato: 400 SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED.
Falhas do provedor. Uma rejeição definitiva (4xx) do PlugNotas ou da SEFIN marca a nota como error e retorna o erro com status 400. Um resultado incerto (timeout, falha de rede, 5xx, resposta inválida) mantém a reserva para conciliação pelo webhook ou pelo provedor e retorna 409 SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED, sem reenviar a nota (fail-closed intencional para evitar NFS-e duplicada). Uma falha de preparação antes de enviar a DPS nacional retorna 422 SERVICE_INVOICE.ISSUE_PREPARATION_FAILED.
Conciliação automática. Uma nota que fica pending/processing por resultado incerto é conciliada por um job a cada 15 minutos, só com consultas ao provedor (DPS na SEFIN, idIntegracao no PlugNotas): se o provedor tem a nota, ela passa a issued com os dados oficiais; se a SEFIN confirma que a DPS não existe após 30 minutos sem alteração, a nota passa a error com error.code SERVICE_INVOICE.ISSUE_NOT_CONFIRMED e uma mensagem orientando emitir novamente (o mesmo vale para uma nota interrompida antes do envio à SEFIN). Nenhuma emissão é reenviada automaticamente.
service_invoices:writeParâmetros
- Idempotency-Keyheader
Opcional. Chave opaca de 8 a 128 caracteres `[A-Za-z0-9_.:-]` para a emissão manual; reutilize-a ao repetir a mesma tentativa após timeout. Ausente: a API gera uma chave interna. Inválida: `400` `SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED`.
Respostas
Emissão processada com sucesso.
Erro de validação da requisição ou dos dados fiscais, Idempotency-Key em formato inválido (SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED) ou rejeição definitiva do provedor (a nota fica com status error).
Token ausente, inválido ou sem empresa selecionada.
Falha de autorização.
Emissão pendente de conciliação ou chave reutilizada com dados diferentes (SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED, SERVICE_INVOICE.ISSUE_IDEMPOTENCY_MISMATCH). Nenhuma nova chamada ao provedor é feita.
Preparação falhou antes de enviar a nota ao provedor (SERVICE_INVOICE.ISSUE_PREPARATION_FAILED); a tentativa é conclusiva e uma nova chave pode ser usada.
Limite de requisições excedido (RATE_LIMIT.EXCEEDED). Por chave: 120 requisições por minuto (janela fixa de 60 s); o 429 da chave traz X-RateLimit-* da chave. Por IP, para tráfego com chave: 600 requisições em 10 minutos; esse 429 traz só Retry-After, sem X-RateLimit-* (os cabeçalhos descrevem apenas o limite da chave). Aguarde Retry-After segundos antes de tentar de novo.
Credencial não pôde ser verificada por falha temporária do servidor (AUTH.SESSION_UNAVAILABLE). Não invalida a chave nem a sessão: repita com backoff.