Primeira nota
Do zero à NF-e autorizada no ambiente simulado. Você só precisa da chave de teste, de um terminal com curl e jq, e destes passos.
No ambiente simulado o motor faz o caminho inteiro (confere o leiaute e o esquema oficial, numera, assina e guarda), mas não fala com a SEFAZ: o protocolo é simulado e a nota não tem valor fiscal. Sem certificado da empresa, ele assina com um certificado de teste próprio. Assim dá para integrar antes de ter o certificado A1 do cliente.
1. Guarde a chave e o endereço
Entre no portal e crie uma chave de teste em Chaves (sem acesso ao portal, peça um convite ao operador do motor). Ela começa com mtr_teste_.
export MOTOR=https://motor.plataformatec.online
export CHAVE=mtr_teste_... # a sua chave
Confira se a chave vale:
curl -s $MOTOR/v1/conta -H "Authorization: Bearer $CHAVE" | jq
A resposta traz o nome da conta e os limites por minuto. Se vier 401 NAO_AUTENTICADO, a chave está errada ou foi revogada.
2. Cadastre a empresa emissora
A emissora é o CNPJ que emite. Este é o corpo de exemplo (emissora.json):
{
"cnpj": "11222333000181",
"razao_social": "EMPRESA DE EXEMPLO LTDA",
"inscricao_estadual": "123456789012",
"inscricao_municipal": "1234567",
"uf": "SP",
"municipio_ibge": "3550308",
"crt": 1,
"ambiente_padrao": "simulado",
"endereco": {
"xLgr": "RUA DO EXEMPLO",
"nro": "100",
"xBairro": "CENTRO",
"xMun": "SAO PAULO",
"CEP": "01001000"
}
}
curl -s $MOTOR/docs/exemplos/emissora.json -o emissora.json
EMISSORA=$(curl -s $MOTOR/v1/emissoras \
-H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-d @emissora.json | jq -r .id)
echo $EMISSORA
A resposta é 201 com o id da emissora. O crt é o regime tributário (1 Simples Nacional, 3 regime normal, 4 MEI). Na sua integração, use os dados reais da empresa: CNPJ, inscrição estadual, endereço e município (código IBGE de 7 dígitos).
3. Emita a NF-e
O corpo segue o leiaute 4.00 da NF-e, com os grupos e os nomes oficiais. Você não manda o emitente (sai da emissora), a chave de acesso, o número nem a data: o motor preenche. Exemplo (nfe.json), uma venda de empresa do Simples Nacional dentro de SP:
{
"emissora_id": "{{emissora_id}}",
"id_externo": "pedido-1001",
"ide": {
"natOp": "VENDA DE MERCADORIA",
"tpNF": "1",
"idDest": "1",
"finNFe": "1",
"indFinal": "0",
"indPres": "1",
"indIntermed": "0"
},
"dest": {
"CNPJ": "11444777000161",
"xNome": "CLIENTE DE EXEMPLO LTDA",
"indIEDest": "9",
"enderDest": {
"xLgr": "RUA DO CLIENTE",
"nro": "20",
"xBairro": "CENTRO",
"cMun": "3550308",
"xMun": "SAO PAULO",
"UF": "SP",
"CEP": "01002000",
"cPais": "1058",
"xPais": "BRASIL"
}
},
"det": [
{
"nItem": "1",
"prod": {
"cProd": "001",
"cEAN": "SEM GTIN",
"xProd": "CANETA AZUL",
"NCM": "96081000",
"CFOP": "5102",
"uCom": "UN",
"qCom": "2.0000",
"vUnCom": "5.00",
"vProd": "10.00",
"cEANTrib": "SEM GTIN",
"uTrib": "UN",
"qTrib": "2.0000",
"vUnTrib": "5.00",
"indTot": "1"
},
"imposto": {
"ICMS": { "ICMSSN102": { "orig": "0", "CSOSN": "102" } },
"PIS": { "PISOutr": { "CST": "99", "vBC": "0.00", "pPIS": "0.0000", "vPIS": "0.00" } },
"COFINS": { "COFINSOutr": { "CST": "99", "vBC": "0.00", "pCOFINS": "0.0000", "vCOFINS": "0.00" } }
}
}
],
"total": {
"ICMSTot": {
"vBC": "0.00", "vICMS": "0.00", "vICMSDeson": "0.00", "vFCP": "0.00",
"vBCST": "0.00", "vST": "0.00", "vFCPST": "0.00", "vFCPSTRet": "0.00",
"vProd": "10.00", "vFrete": "0.00", "vSeg": "0.00", "vDesc": "0.00",
"vII": "0.00", "vIPI": "0.00", "vIPIDevol": "0.00", "vPIS": "0.00",
"vCOFINS": "0.00", "vOutro": "0.00", "vNF": "10.00"
}
},
"transp": { "modFrete": "9" },
"pag": { "detPag": [ { "tPag": "01", "vPag": "10.00" } ] }
}
curl -s $MOTOR/docs/exemplos/nfe.json | sed "s/{{emissora_id}}/$EMISSORA/" > nfe.json
DOC=$(curl -s $MOTOR/v1/nfe \
-H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1001" \
-d @nfe.json | jq -r .id)
echo $DOC
A resposta é 202 com o documento em processando, já com número, série e chave de acesso. Se o pedido tiver erro de preenchimento, a resposta é 422 e a lista erros diz o campo e o motivo, antes de qualquer transmissão.
A Idempotency-Key protege contra nota em dobro: se a conexão cair e você repetir o pedido com a mesma chave, a resposta é o documento que já existe (200), e não uma nota nova. Use o identificador do pedido no seu sistema.
4. Acompanhe até o desfecho
curl -s $MOTOR/v1/documentos/$DOC -H "Authorization: Bearer $CHAVE" | jq
Em um ou dois segundos o status passa de processando para autorizado, com protocolo e autorizado_em. Os outros desfechos são rejeitado e denegado (com codigo_sefaz, motivo_sefaz e a rejeicao explicada) e contingencia na NFC-e. Em produção, não fique consultando: cadastre um webhook e o motor avisa.
5. Baixe o XML e a DANFE
curl -s $MOTOR/v1/documentos/$DOC/xml -H "Authorization: Bearer $CHAVE" -o nota.xml
curl -s $MOTOR/v1/documentos/$DOC/pdf -H "Authorization: Bearer $CHAVE" -o danfe.pdf
O XML é o nfeProc (nota assinada com o protocolo), o arquivo que a empresa guarda por cinco anos. O PDF é a DANFE.
6. Teste a rejeição
No simulado, o campo simulacao escolhe o desfecho, para você testar o tratamento de erro do seu sistema (rejeicao.json):
{
"simulacao": { "resultado": "rejeitar" }
}
jq -s '.[0] * .[1]' nfe.json <(curl -s $MOTOR/docs/exemplos/rejeicao.json) > rejeitar.json
curl -s $MOTOR/v1/nfe -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1002" -d @rejeitar.json | jq -r .id
Os valores são autorizar, rejeitar e denegar. Fora do simulado, o campo é recusado.
7. NFS-e nacional
A NFS-e segue o leiaute da DPS do Sistema Nacional. A mesma emissora serve, desde que tenha inscricao_municipal (nfse.json):
{
"emissora_id": "{{emissora_id}}",
"id_externo": "os-2001",
"toma": {
"CNPJ": "11444777000161",
"xNome": "CLIENTE DE EXEMPLO LTDA",
"end": {
"endNac": { "cMun": "3550308", "CEP": "01002000" },
"xLgr": "RUA DO CLIENTE",
"nro": "20",
"xBairro": "CENTRO"
}
},
"serv": {
"locPrest": { "cLocPrestacao": "3550308" },
"cServ": {
"cTribNac": "010701",
"xDescServ": "DESENVOLVIMENTO DE PROGRAMAS DE COMPUTADOR SOB ENCOMENDA",
"cNBS": "115011000"
}
},
"valores": {
"vServPrest": { "vServ": "1000.00" },
"trib": {
"tribMun": { "tribISSQN": "1", "tpRetISSQN": "1", "pAliq": "2.00" },
"totTrib": { "indTotTrib": "0" }
}
}
}
curl -s $MOTOR/docs/exemplos/nfse.json | sed "s/{{emissora_id}}/$EMISSORA/" > nfse.json
curl -s $MOTOR/v1/nfse -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-H "Idempotency-Key: os-2001" -d @nfse.json | jq
Na NFS-e a chave de acesso (50 dígitos) só existe depois da autorização: ela vem do Sistema Nacional. Antes de emitir em homologação, confira se o município é conveniado (GET /v1/municipios/{ibge}/convenio) e a alíquota do serviço (GET /v1/municipios/{ibge}/servicos/{codigo}/aliquota).
8. NFC-e
O cupom usa o mesmo corpo da NF-e em POST /v1/nfce, com indFinal 1 e o destinatário opcional. Ele exige o CSC da emissora (PUT /v1/emissoras/{id}/csc), que entra no QR Code. No simulado, qualquer CSC com 16 caracteres ou mais serve. Detalhes na referência.
Depois do simulado
- Envie o certificado A1 da empresa:
PUT /v1/emissoras/{id}/certificado, emmultipart/form-datacom os camposarquivo(o .pfx) esenha. O motor guarda cifrado e nunca devolve. - Emita com
"ambiente": "homologacao". A nota vai para a SEFAZ de verdade, sem valor fiscal. É aqui que aparecem as rejeições de regra fiscal que o simulado não confere (cadastro do destinatário, NCM, CFOP). - Para produção, peça ao operador a chave de produção e a liberação da emissora.
A emissora, o certificado, as séries e os webhooks também podem ser cadastrados pelo portal, sem chamar a API.