E-mail de notas
Enviar e-mail da nota
Aceita o envio de uma nota autorizada por e-mail ao cliente; a entrega é assíncrona.
/openapi/v2/empresas/{empresaId}/emailstoken, timestamp e sign, veja Autenticação.Manda uma nota já autorizada (NF-e, NFS-e, CT-e ou DC-e) por e-mail, com o corpo do modelo e, se pedido, o PDF e o XML anexos. A chamada é assíncrona: HTTP 200 devolve o emailId e o status de aceitação; o resultado chega por email.sent / email.failed ou pela consulta. id é a chave de idempotência; enquanto um e-mail da mesma nota está em andamento, outro envio responde 409. A nota só é enviada quando você chama este endpoint: nada sai automaticamente na autorização.
Parâmetros de caminho
empresaId* | string | Identificador da empresa |
* Campo obrigatório
Corpo da requisição
id* | string | Identificador da requisição |
tipoDocumento* | string | Tipo de documento |
documentoId* | string | Identificador da nota |
templateId | string | Identificador do modelo |
enviarPdf* | bool | Anexar PDF |
enviarXml* | bool | Anexar XML |
destinatarios | array | Destinatários |
* Campo obrigatório
emailId para a consulta; acompanhe o resultado pelo webhook ou pela consulta.emailId | string | Identificador do e-mail |
id | string | Identificador da requisição |
status | string | Status na aceitação |
tipoDocumento | string | Tipo de documento |
documentoId | string | Identificador da nota |
templateId | string | Modelo usado |
destinatarios | array | Destinatários efetivos |
anexos | array | Anexos pedidos |
O HTTP 200 é só a aceitação: o e-mail é montado e enviado depois, por uma tarefa da plataforma. O remetente é o endereço da plataforma (não dá para usar o seu domínio); o nome exibido é a razão social da empresa e o responder-para é o e-mail cadastrado da empresa. O resultado chega por email.sent / email.failed (assinatura explícita, veja Registrar webhook) ou pela consulta.
Só o corpo e o XML
NFS-e com modelo escolhido e destinatário informado; enviarPdf = false evita gerar o DANFSe. O XML anexo se chama NFSe-{chave}.xml.
{"id": "mail-nfse-000123","tipoDocumento": "NFSe","documentoId": "PED-20260918-001","templateId": "2103150000000000002","enviarPdf": false,"enviarXml": true,"destinatarios": ["financeiro@cliente.com.br"]}
id* | string | Identificador da requisição |
tipoDocumento* | string | Tipo de documento |
documentoId* | string | Identificador da nota |
templateId | string | Identificador do modelo |
enviarPdf* | bool | Anexar PDF |
enviarXml* | bool | Anexar XML |
destinatarios | array | Destinatários |
* Campo obrigatório
PDF e XML para o e-mail da nota
Sem destinatarios a plataforma usa o e-mail do cliente informado na emissão; só NF-e e NFS-e o têm, CT-e e DC-e exigem destinatarios. Sem templateId usa o modelo padrão do tipo. Se o PDF ou o XML ainda não estiver disponível, o e-mail espera em Aguardando em vez de sair incompleto.
{"id": "email-pedido-8842-1","tipoDocumento": "NFe","documentoId": "pedido-8842","enviarPdf": true,"enviarXml": true}
id* | string | Identificador da requisição |
tipoDocumento* | string | Tipo de documento |
documentoId* | string | Identificador da nota |
enviarPdf* | bool | Anexar PDF |
enviarXml* | bool | Anexar XML |
* Campo obrigatório
NFS-e de São Paulo aguardando a chave
A NFS-e do sistema municipal de São Paulo recebe a chave de 50 dígitos depois, pelo ambiente nacional. Enquanto ela não chega, o envio é aceito como Aguardando com motivoEspera = chaveAcesso e reconferido a cada 30 segundos, por até 120 minutos; passado esse prazo vira Falha e motivoFalha diz o que faltou. A resposta abaixo é a da aceitação.
{"emailId": "2103160000000000002","id": "mail-sp-000045","status": "Aguardando","tipoDocumento": "NFSe","documentoId": "SP-20260928-045","templateId": "2103150000000000002","destinatarios": ["financeiro@cliente.com.br"],"anexos": ["pdf", "xml"]}
status* | string | Status na aceitação |
* Campo obrigatório
Mesma nota em andamento: 409
Enquanto um e-mail da mesma nota (mesma empresa, tipoDocumento e documentoId) não chega a Enviado ou Falha, um novo envio com outro id é recusado com HTTP 409 e 10021015; a mensagem traz o emailId e o status do e-mail em andamento. Espere o callback ou consulte, e então reenvie com um id novo.
[{"codigo": "10021015","mensagem": "O e-mail anterior desta nota ainda não foi concluído: emailId=2103160000000000001 status=Enfileirado"}]
Reenvio idempotente
Repetir uma chamada com o mesmo id (na mesma empresa) devolve o resultado original sem criar outro e-mail, mesmo que o corpo seja diferente; status reflete o estado atual. Para mandar de novo a mesma nota use um id novo depois do estado terminal.
{"emailId": "2103160000000000001","id": "email-pedido-8842-1","status": "Enviado","tipoDocumento": "NFe","documentoId": "pedido-8842","templateId": "2103150000000000001","destinatarios": ["comprador@exemplo.com"],"anexos": ["pdf", "xml"]}
status* | string | Status na aceitação |
* Campo obrigatório
Aguardando ──► Enfileirado ──► Enviando ──┬─► Enviado└─► Falha
Aguardando só existe enquanto falta a chave, o PDF ou o XML; não consome tentativas. Enviando que falha na saída volta a Enfileirado com espera crescente, até 5 tentativas. Enviado e Falha são terminais e liberam a nota para um novo envio. O significado de cada status e de motivoEspera está em Consultar e-mail.
tipoDocumentoTipo de documento
| Valores | Significado |
|---|---|
| NFe | NF-e, nota fiscal de mercadorias |
| NFSe | NFS-e, nota fiscal de serviços |
| CTe | CT-e, conhecimento de transporte |
| DCe | DC-e, declaração de conteúdo |
statusStatus do e-mail
Na primeira aceitação só Aguardando ou Enfileirado; os demais aparecem no reenvio idempotente.
| Valores | Significado |
|---|---|
| Aguardando | Aceito, aguardando dados da nota; motivoEspera diz o quê |
| Enfileirado | Na fila, dados completos, aguardando envio |
| Enviando | Um worker está renderizando e enviando |
| Enviado | Entregue ao serviço de envio; terminal |
| Falha | Falha definitiva; motivoFalha explica; terminal |
anexos[]Anexos
Nome do arquivo: {tipo}-{chave}.pdf / .xml, por exemplo NFSe-3550...077.xml.
| Valores | Significado |
|---|---|
| Comprovante em PDF: DANFE, DANFSe, DACTE ou DACE | |
| xml | XML autorizado, o original legal |
| Código | HTTP | |
|---|---|---|
| 10001001 | 400 | Falha de validação de campos: id ou documentoId em branco ou acima de 64, tipoDocumento fora dos valores, enviarPdf / enviarXml ausentes, mais de 5 destinatários ou e-mail inválido; uma entrada por campo. |
| 10003000 | 404 | empresaId não encontrado. |
| 10021001 | 404 | Modelo de e-mail não encontrado: o templateId não existe ou não é deste integrador. |
| 10021002 | 400 | Modelo de e-mail desativado, ou o tipo de documento do modelo é diferente do da nota. |
| 10021010 | 404 | Nota não encontrada ou não pertence a esta empresa. Confira documentoId, tipoDocumento e empresaId. |
| 10021011 | 400 | Nota ainda não autorizada, não pode ser enviada ao cliente; também para nota cancelada ou substituída. Aguarde a autorização. |
| 10021012 | 400 | O tipo de documento não tem modelo padrão; informe templateId ou marque um modelo com padrao = true. |
| 10021013 | 400 | Sem destinatário: destinatarios não informado e a nota não tem e-mail do cliente. CT-e e DC-e sempre exigem destinatarios. |
| 10021015 | 409 | O e-mail anterior desta nota ainda não terminou; a mensagem traz emailId e status. Espere Enviado ou Falha e reenvie com um id novo. |