Motor de Emissão

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

  1. Envie o certificado A1 da empresa: PUT /v1/emissoras/{id}/certificado, em multipart/form-data com os campos arquivo (o .pfx) e senha. O motor guarda cifrado e nunca devolve.
  2. 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).
  3. 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.