Voltar para ""

Emissão de NFS-e em Lote

O InvoiCy permite enviar vários RPS de NFS-e em uma única requisição, evitando uma chamada à API por documento. Esse envio em lote reduz o número de requisições, agiliza a integração de grandes volumes e mantém o mesmo processo de autenticação e os mesmos layouts de emissão utilizados no envio individual.

A montagem do lote depende da integração utilizada (JSON ou XML), pois cada um agrupa os documentos em um nível diferente da estrutura. As seções a seguir detalham as duas formas.

Estrutura do lote

O ponto de atenção mais importante é que o nível de agrupamento muda conforme o formato:

FORMATO	ENVELOPE DO LOTE	NÍVEL DE REPETIÇÃO	COMO ADICIONAR MAIS DOCUMENTOS
JSON	Array raiz [...]	Objeto Documento	Adicionar um novo objeto { "Documento": { ... } } ao array
XML	Elemento Envio	Grupo RPS	Adicionar um novo RPS dentro do mesmo Envio

Ou seja: no JSON, cada RPS vai dentro do seu próprio envelope Documento e o lote é o array desses envelopes. No XML, todos os RPS compartilham um único envelope <Envio>.

Os exemplos abaixo estão reduzidos para destacar a estrutura do lote. Os arquivos completos e prontos para uso estão disponíveis no repositório de integração:

• Exemplo de lote NFS-e em JSON
• Exemplo de lote NFS-e em XML

O conteúdo completo de cada RPS (grupos Prestador, ListaItens, Servico, Tomador, IBSCBS etc.) segue o Layout de envio do módulo NFS-e.

Envio em JSON

No formato JSON, o lote é um array na raiz do corpo da requisição. Cada elemento do array é um objeto Documento independente, com um único RPS em sua lista RPS.

[
    {
        "Documento": {
            "ModeloDocumento": "NFSE",
            "Versao": 1.00,
            "RPS": [
                {
                    "RPSNumero": 5472,
                    "RPSSerie": "770",
                    "RPSTipo": 1,
                    "dEmis": "2026-07-21T10:11:37",
                    "dCompetencia": "2026-07-21T10:11:37",
                    "tpAmb": 2,
                    "Status": 1,
                    "Prestador": {
                        "CNPJ_prest": "99999999999999",
                        "xNome": "MIGRATE",
                        "IM": "99999999999999"
                    }
                }
                ...
            ]
        }
    },
    {
        "Documento": {
            "ModeloDocumento": "NFSE",
            "Versao": 1.00,
            "RPS": [
                {
                    "RPSNumero": 5474,
                    "RPSSerie": "770",
                    "RPSTipo": 1
                }
                ...
            ]
        }
    }
]

Para incluir mais documentos no lote, adicione um novo objeto { "Documento": { ... } } ao array, separando-o do anterior por vírgula. Cada objeto deve conter seus próprios dados de RPS.

Envio em XML

No formato XML, o lote é um único elemento <Envio>. Cada documento adicional é representado por um novo grupo <RPS> dentro do mesmo envelope.

<Envio>
    <ModeloDocumento>NFSE</ModeloDocumento>
    <Versao>1.00</Versao>
    <RPS>
        <RPSNumero>5477</RPSNumero>
        <RPSSerie>770</RPSSerie>
        <RPSTipo>1</RPSTipo>
        <dEmis>2026-07-21T10:33:37</dEmis>
        <dCompetencia>2026-07-21T00:00:00</dCompetencia>
        <tpAmb>2</tpAmb>
        <Status>1</Status>
        <Prestador>
            <CNPJ_prest>99999999999999</CNPJ_prest>
            <xNome>MIGRATE</xNome>
            <IM>99999999999999</IM>
        </Prestador>
        ...
    </RPS>
    <RPS>
        <RPSNumero>5478</RPSNumero>
        <RPSSerie>770</RPSSerie>
        <RPSTipo>1</RPSTipo>
        ...
    </RPS>
</Envio>

Para incluir mais documentos no lote, adicione um novo grupo <RPS> dentro do mesmo <Envio>.

Processamento e retorno do lote

O processamento é feito por documento: cada RPS enviado é validado e autorizado de forma independente, e o retorno traz o resultado individual de cada um. Por isso, cada RPS deve ter numeração própria (RPSNumero), respeitando a série informada em RPSSerie.

Um documento rejeitado não invalida os demais do lote. A exceção são os municípios com envio sequencial, em que a ordem dos documentos e o tratamento de rejeições seguem as regras descritas em Emissão Sequencial de RPS.