Cria um lote de emissão
Até 5.000 notas num lote (com a chave de sandbox, 100), por JSON ou pela planilha do painel. O lote passa pela mesma validação, pela mesma normalização e pela mesma fila da planilha do painel. Sempre 202: o lote é assíncrono. Acompanhe por GET /v1/lotes/{id} ou pelo webhook LOTE_EMISSAO_CONCLUIDO.
Duas formas de entrada, mesma rota:
- application/json: { "empresa_id", "modelo"?, "ao_validar"?, "itens": [...] }. Cada item é exatamente o corpo de POST /v1/nfse (mesmos campos, mesma validação), com referencia opcional por item.
- multipart/form-data: campo planilha (.xlsx ou .csv separado por vírgula, no template oficial, qualquer dos três layouts) e os campos empresa_id, modelo e ao_validar no formulário.
ao_validar:
- emitir_validas (padrão): as linhas válidas entram na fila assim que o lote é validado; as inválidas ficam com erro no resultado, e você corrige com POST /v1/lotes/{id}/reprocessamento.
- aguardar: o lote para depois da validação. Confira o resultado e chame POST /v1/lotes/{id}/emissao. Serve para quem quer tudo ou nada.
Reenvio seguro com referencia. Mande sempre uma referencia por item (o seu número de pedido, por exemplo). Se o mesmo lote for enviado de novo (um timeout, um retry automático), a linha cuja referência já virou nota não vira outra nota: aparece como ja_existente, com o nfse_id da nota que já existe. Se o conteúdo da linha mudou, divergente: true avisa, e mesmo assim nenhuma nota nova é criada. Referência repetida dentro do mesmo lote é erro nas linhas envolvidas (referencia_duplicada_no_lote), e nenhuma delas vira nota.
⚠️ Linha sem referencia não tem essa proteção. Reenviar um lote sem referências emite as notas de novo. Em lote, mande sempre referencia.
Use também Idempotency-Key: a mesma chave com o mesmo corpo devolve o mesmo lote; com corpo diferente, 409 idempotencia_conflito. Na planilha, o "corpo" é o arquivo (hash) mais os campos do formulário.
A prontidão da empresa é avaliada uma vez, antes de criar o lote: bloqueio devolve 412 empresa_nao_pronta, como no POST /v1/nfse, e nada é criado.
Limite de requisições: um POST /v1/lotes conta como uma chamada, qualquer que seja o número de itens.
Itens de lote entram na fila de emissão atrás das notas avulsas (POST /v1/nfse): um lote grande não atrasa a nota de outro cliente.
Request
- Base URL: https://api.sudrel.com.br/api
- URL: https://api.sudrel.com.br/api/v1/lotes
- Auth: HTTP bearer
Headers
Identificador único da SUA tentativa de emissão (ex.: um UUID gerado pelo seu sistema). Mesma chave e mesmo corpo: mesma resposta, sem nota nova, por 30 dias. Mesma chave e corpo diferente: 409 nas primeiras 24 horas; depois disso, a chave vale como nova.
Request body
Example request
{
"itens": [
{
"tomador": {
"documento": "11222333000181",
"endereco": {
"cep": "40020000"
}
},
"valor": "1500.00",
"servico": {
"codigo_nacional": "010701",
"competencia": "2026-09",
"nbs": "1.1302.21.00",
"obra": {
"endereco": {
"cep": "40020000"
}
}
},
"retencoes": {
"pis": {
"valor": "1500.00",
"aliquota": "2.5"
},
"cofins": {
"valor": "1500.00",
"aliquota": "2.5"
},
"csll": {
"valor": "1500.00",
"aliquota": "2.5"
},
"irrf": {
"valor": "1500.00",
"aliquota": "2.5"
},
"inss": {
"valor": "1500.00",
"aliquota": "2.5"
}
},
"apuracao_propria": {
"pis": {
"valor": "1500.00",
"aliquota": "2.5"
},
"cofins": {
"valor": "1500.00",
"aliquota": "2.5"
}
},
"iss": {
"aliquota": "2.5"
}
}
]
}Response
Lote criado. Validação e emissão seguem em segundo plano.
Changes
No recorded changes to this operation across all 1 revision of this API.