Integração de NF-e passo a passo (cURL)

export API="https://www.fiscal.versianecode.com.br/api/v1"        # URL da API desta instalação
export TOKEN="nfk_SEU_TOKEN"                    # nunca coloque o token em código público
export EMPRESA="EMPRESA_001"                    # código da empresa (omita se o token enxerga só uma)
export ERP="https://erp.exemplo.com/api"        # API do SEU sistema (loja/ERP) - exemplo
export ERP_TOKEN="token-do-seu-erp"

# saldo de créditos
curl -s "$API/financeiro/saldo" -H "Authorization: Bearer $TOKEN" | jq

# a SEFAZ está respondendo?
curl -s "$API/sefaz/status" -H "Authorization: Bearer $TOKEN" | jq

# a empresa está pronta para emitir? (emitente, certificado, natureza, tributação)
curl -s "$API/configuracao-fiscal/validar?empresa=$EMPRESA" -H "Authorization: Bearer $TOKEN" | jq

PEDIDO_ID=12345
curl -s "$ERP/pedidos/$PEDIDO_ID" -H "Authorization: Bearer $ERP_TOKEN" -o pedido.json
jq . pedido.json

{
  "id": 12345,
  "cliente_id": 77,
  "forma_pagamento": "pix",
  "itens": [
    { "sku": "CAMISA-AZUL-M", "quantidade": 2, "preco": 59.90 },
    { "sku": "BONE-PRETO",    "quantidade": 1, "preco": 35.00 }
  ]
}

CLIENTE_ID=$(jq -r '.cliente_id' pedido.json)
curl -s "$ERP/clientes/$CLIENTE_ID" -H "Authorization: Bearer $ERP_TOKEN" -o cliente.json
jq . cliente.json

{
  "nome": "Maria da Silva", "cpf_cnpj": "123.456.789-09", "email": "maria@exemplo.com", "telefone": "(31) 99999-0000",
  "ie": "", "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
  "cod_municipio_ibge": "3106200", "cidade": "Belo Horizonte", "uf": "MG", "cep": "30110-000"
}

mkdir -p produtos
for SKU in $(jq -r '.itens[].sku' pedido.json); do
  curl -s "$ERP/produtos/$SKU" -H "Authorization: Bearer $ERP_TOKEN" -o "produtos/$SKU.json"
done
jq . produtos/CAMISA-AZUL-M.json

{ "sku": "CAMISA-AZUL-M", "nome": "Camisa Azul M", "ncm": "61091000", "origem": 0, "unidade": "UN", "ean": "7891234567895", "preco": 59.90 }

curl -s -X POST "$API/produtos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "empresa": "'"$EMPRESA"'",
    "codigo": "CAMISA-AZUL-M", "descricao": "Camisa Azul M", "ncm": "61091000",
    "origem": "0", "unidade": "UN", "gtin": "7891234567895", "preco": 59.90
  }' | jq

# mapa codigo -> id dos produtos já cadastrados na API
curl -s "$API/produtos?empresa=$EMPRESA" -H "Authorization: Bearer $TOKEN" \
  | jq 'reduce .itens[] as $p ({}; .[$p.codigo] = $p.id)' > produtos_api.json

for ARQ in produtos/*.json; do
  # converte o formato do seu sistema para o da API
  BODY=$(jq -c --arg e "$EMPRESA" '{empresa:$e, codigo:.sku, descricao:(.nome[0:120]), ncm:.ncm,
                                    origem:(.origem|tostring), unidade:.unidade, gtin:.ean, preco:.preco}' "$ARQ")
  COD=$(echo "$BODY" | jq -r .codigo)
  ID=$(jq -r --arg c "$COD" '.[$c] // empty' produtos_api.json)
  if [ -z "$ID" ]; then
    curl -s -X POST "$API/produtos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$BODY" | jq -c '{acao:"criado",codigo:.codigo,id:.id}'
  else
    curl -s -X PUT "$API/produtos/$ID" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$BODY" | jq -c '{acao:"atualizado",id:.id}'
  fi
done

# converte o cliente do seu sistema para o formato da API (só dígitos em CPF/CNPJ/CEP)
jq -c '{
  cpf_cnpj: (.cpf_cnpj | gsub("[^0-9]";"")),
  nome: .nome, email: .email, fone: (.telefone | gsub("[^0-9]";"")),
  ie: (.ie // ""),
  endereco: { logradouro: .logradouro, numero: .numero, bairro: .bairro,
              cod_municipio: .cod_municipio_ibge, municipio: .cidade, uf: .uf,
              cep: (.cep | gsub("[^0-9]";"")) }
}' cliente.json > cliente_api.json
cat cliente_api.json

# junta pedido + cliente + itens no formato da API
jq -c --arg e "$EMPRESA" --slurpfile c cliente_api.json '{
  empresa: $e,
  pedido: ("PED-" + (.id|tostring)),            # sua chave de idempotência: o mesmo pedido nunca gera 2 notas
  cliente: $c[0],
  itens: [ .itens[] | { codigo: .sku, quantidade: .quantidade, valor: .preco } ],
  pagamento: .forma_pagamento,                  # pix, dinheiro, cartao_credito, boleto...
  observacoes: ("Pedido " + (.id|tostring))
}' pedido.json > nfe.json
jq . nfe.json

{
  "empresa": "EMPRESA_001",
  "pedido": "PED-12345",
  "cliente": { "cpf_cnpj": "12345678909", "nome": "Maria da Silva", "email": "maria@exemplo.com",
               "endereco": { "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
                             "cod_municipio": "3106200", "municipio": "Belo Horizonte", "uf": "MG", "cep": "30110000" } },
  "itens": [ { "codigo": "CAMISA-AZUL-M", "quantidade": 2, "valor": 59.9 },
             { "codigo": "BONE-PRETO",    "quantidade": 1, "valor": 35 } ],
  "pagamento": "pix",
  "observacoes": "Pedido 12345"
}

curl -s -X POST "$API/fiscal/preview" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -c '. + {modelo: 55}' nfe.json)" | jq

{ "success": false, "ready_to_issue": false,
  "error": { "code": "FISCAL_CONFIGURATION_REQUIRED",
             "missing": [ "NCM do produto BONE-PRETO", "produto XYZ nao cadastrado" ] } }

curl -s -X POST "$API/nfe" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: PED-12345" \
  -d @nfe.json | tee resposta.json | jq

{
  "success": true, "status": "AUTORIZADA", "id": "43", "numero": 1, "serie": 1,
  "chave": "3126096505750400019355001000000001...", "protocolo": "131260152908273",
  "xml": "/api/v1/nfe/43/xml", "danfe": "/api/v1/nfe/43/danfe", "request_id": "req_40d1822f3cdb8073b965"
}

curl -s -X POST "$API/nfe" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: PED-12345" -H "Prefer: respond-async" \
  -d @nfe.json | tee resposta.json | jq
# 202 { "solicitacao_id": "sol_...", "status": "RECEBIDA", ... }

SOL=$(jq -r '.solicitacao_id' resposta.json)
curl -s "$API/fiscal/solicitacoes/$SOL" -H "Authorization: Bearer $TOKEN" | jq '{status, descricao_status, documento_id, chave}'

ID=$(jq -r '.id' resposta.json)
curl -s "$API/nfe/$ID" -H "Authorization: Bearer $TOKEN" | jq '{status, numero, chave, protocolo}'
curl -s "$API/nfe/$ID/eventos" -H "Authorization: Bearer $TOKEN" | jq

for i in $(seq 1 30); do
  ST=$(curl -s "$API/fiscal/solicitacoes/$SOL" -H "Authorization: Bearer $TOKEN" | jq -r .status)
  echo "tentativa $i: $ST"
  case "$ST" in AUTORIZADA|REJEITADA|ACAO_NECESSARIA|CANCELADA) break;; esac
  sleep 5
done

curl -s -X POST "$API/webhooks" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com/webhooks/fiscal","eventos":["nfe.authorized","nfe.rejected","nfe.cancelled"]}' | jq
# guarde o "segredo" devolvido (aparece uma única vez): valida a assinatura HMAC-SHA256 de "timestamp.corpo"

curl -s -X POST "$API/webhooks/ID/testar" -H "Authorization: Bearer $TOKEN" | jq   # envia um evento de teste

curl -s "$API/nfe/$ID/xml"   -H "Authorization: Bearer $TOKEN" -o "nfe-$ID.xml"
curl -s "$API/nfe/$ID/danfe" -H "Authorization: Bearer $TOKEN" -o "danfe-$ID.pdf"

curl -s -X PUT "$ERP/pedidos/12345" -H "Authorization: Bearer $ERP_TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -c '{nfe_chave:.chave, nfe_numero:.numero, nfe_status:.status}' resposta.json)"

# cancelamento (justificativa de 15 a 255 caracteres; prazo definido pela SEFAZ/UF)
curl -s -X POST "$API/nfe/$ID/cancelamento" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"justificativa":"Pedido cancelado a pedido do cliente antes da entrega"}' | jq

# carta de correção (não altera valores nem destinatário; até 20 por nota)
curl -s -X POST "$API/nfe/$ID/cce" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"correcao":"Corrigir o complemento do endereco de entrega para: Apto 302"}' | jq

# inutilizar uma faixa de números não usada
curl -s -X POST "$API/inutilizacao" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"modelo":55,"serie":1,"numero_inicial":10,"numero_final":12,"justificativa":"Numeracao pulada por falha no sistema"}' | jq

#!/usr/bin/env bash
set -euo pipefail
: "${API:?}" "${TOKEN:?}" "${ERP:?}" "${ERP_TOKEN:?}"
EMPRESA="${EMPRESA:-}"
PEDIDO_ID="${1:?uso: $0 ID_DO_PEDIDO}"
H=(-H "Authorization: Bearer $TOKEN")
J=(-H "Content-Type: application/json")
E=(-H "Authorization: Bearer $ERP_TOKEN")
mkdir -p work && cd work

echo "1) lendo pedido, cliente e produtos no sistema externo"
curl -fsS "$ERP/pedidos/$PEDIDO_ID" "${E[@]}" -o pedido.json
curl -fsS "$ERP/clientes/$(jq -r .cliente_id pedido.json)" "${E[@]}" -o cliente.json
mkdir -p produtos
for SKU in $(jq -r '.itens[].sku' pedido.json); do
  curl -fsS "$ERP/produtos/$SKU" "${E[@]}" -o "produtos/$SKU.json"
done

echo "2) sincronizando produtos na API fiscal"
curl -fsS "$API/produtos${EMPRESA:+?empresa=$EMPRESA}" "${H[@]}" \
  | jq 'reduce .itens[] as $p ({}; .[$p.codigo] = $p.id)' > produtos_api.json
for ARQ in produtos/*.json; do
  BODY=$(jq -c --arg e "$EMPRESA" '{empresa:$e, codigo:.sku, descricao:(.nome[0:120]), ncm:.ncm,
        origem:(.origem|tostring), unidade:.unidade, gtin:.ean, preco:.preco}' "$ARQ")
  ID=$(jq -r --arg c "$(echo "$BODY" | jq -r .codigo)" '.[$c] // empty' produtos_api.json)
  if [ -z "$ID" ]; then curl -fsS -X POST "$API/produtos" "${H[@]}" "${J[@]}" -d "$BODY" >/dev/null
  else curl -fsS -X PUT "$API/produtos/$ID" "${H[@]}" "${J[@]}" -d "$BODY" >/dev/null; fi
done

echo "3) montando o JSON da NF-e"
jq -c '{cpf_cnpj:(.cpf_cnpj|gsub("[^0-9]";"")), nome, email, fone:(.telefone|gsub("[^0-9]";"")), ie:(.ie//""),
  endereco:{logradouro, numero, bairro, cod_municipio:.cod_municipio_ibge, municipio:.cidade, uf, cep:(.cep|gsub("[^0-9]";""))}}' cliente.json > cliente_api.json
jq -c --arg e "$EMPRESA" --slurpfile c cliente_api.json '{empresa:$e, pedido:("PED-"+(.id|tostring)), cliente:$c[0],
  itens:[.itens[]|{codigo:.sku, quantidade, valor:.preco}], pagamento:.forma_pagamento}' pedido.json > nfe.json

echo "4) pré-visualizando"
PRE=$(curl -sS -X POST "$API/fiscal/preview" "${H[@]}" "${J[@]}" -d "$(jq -c '.+{modelo:55}' nfe.json)")
if [ "$(echo "$PRE" | jq -r '.ready_to_issue // false')" != "true" ]; then
  echo "NAO ESTA PRONTO PARA EMITIR:"; echo "$PRE" | jq '.error'; exit 2
fi

echo "5) emitindo (assíncrono)"
curl -sS -X POST "$API/nfe" "${H[@]}" "${J[@]}" -H "Idempotency-Key: PED-$PEDIDO_ID" -H "Prefer: respond-async" -d @nfe.json > resposta.json
SOL=$(jq -r '.solicitacao_id // empty' resposta.json)

echo "6) aguardando o resultado"
DOC_ID=""
if [ -n "$SOL" ]; then
  for i in $(seq 1 40); do
    R=$(curl -sS "$API/fiscal/solicitacoes/$SOL" "${H[@]}"); ST=$(echo "$R" | jq -r .status)
    echo "   $ST"
    case "$ST" in
      AUTORIZADA) DOC_ID=$(echo "$R" | jq -r .documento_id); break;;
      REJEITADA|ACAO_NECESSARIA|CANCELADA) echo "$R" | jq; exit 3;;
    esac
    sleep 5
  done
else
  DOC_ID=$(jq -r .id resposta.json)   # a API respondeu direto (sincrono)
fi
[ -n "$DOC_ID" ] || { echo "sem resultado final ainda: consulte depois a solicitacao $SOL"; exit 4; }

echo "7) baixando XML e DANFE"
curl -fsS "$API/nfe/$DOC_ID/xml"   "${H[@]}" -o "nfe-$PEDIDO_ID.xml"
curl -fsS "$API/nfe/$DOC_ID/danfe" "${H[@]}" -o "danfe-$PEDIDO_ID.pdf"
curl -fsS "$API/nfe/$DOC_ID" "${H[@]}" | jq '{status, numero, chave, protocolo}'
echo "OK: work/nfe-$PEDIDO_ID.xml e work/danfe-$PEDIDO_ID.pdf"