Pular para conteúdo

Notas Fiscais e DANFE

A Gubee mantém dois serviços downstream para notas fiscais, e o BFF expõe os dois na API de integração. Esta página explica a diferença, o modelo de dados e como baixar os arquivos (PDF DANFE, XML, carta de correção).

Os dois serviços

Surface API Serviço downstream Quando usar
/integration/invoices/* (legacy) invoiceservice Apenas listar e pegar URL de download de NFs já emitidas (qualquer origem: marketplace, painel, API)
/integration/invoicer/invoices/* (recomendado) invoicerservice Emissão ativa de NF: sale, devolution, reversal, complementary, correction letter, cancel, preview DANFE

Ambos retornam dados fiscais persistedos na SEFAZ. A diferença é que o invoicer (novo) emite NF; o invoice (legacy) só lê.

Recomendado

Para qualquer fluxo ativo (emitir, cancelar, corrigir), use /integration/invoicer/invoices/*. O legacy existe só pra compatibilidade com integrações antigas que só precisavam ler.

Modelo de dados

Uma Nota Fiscal na Gubee tem:

Campo Descrição
id Identificador único interno da NF
orderId Pedido associado
number Número da NF (ex.: 123456)
series Série (ex.: 1)
model Modelo fiscal: 55 (NF-e), 65 (NFC-e), 1 (AVULSA)
status AUTHORIZED, CANCELED, REJECTED, PROCESSING
issueDate Data de emissão (ISO 8601)
totalValue Valor total da NF
danfeLink URL pré-assinada do PDF DANFE (~1h de validade)
xmlLink URL pré-assinada do XML (mesmo padrão)
correctionLetters Lista de cartas de correção associadas

Tipos de emissão

Cobertos pelo /integration/invoicer/invoices/*:

Tipo Endpoint Descrição
Sale (Saída) POST /sale NF normal de venda — emitida após pagamento
Reversal (Estorno) POST /reversal NF de estorno — cancela uma sale não autorizada
Devolution (Devolução) POST /devolution NF de devolução — cliente devolveu mercadoria
Complementary (Complementar) POST /complementary NF complementar de valor — ajusta preço para cima
Cancel (Cancelamento) DELETE /cancel-invoice/{id} Cancela NF autorizada (prazo legal: 24h)
Correction Letter (CC-e) POST /correction-letter/{id} Carta de correção — corrige dados sem cancelar
Preview DANFE POST /preview-danfe Pré-visualiza DANFE sem emitir NF

Como baixar os arquivos

A Gubee não retorna o binário do PDF/XML direto na resposta da API. Em vez disso, retorna uma URL pré-assinada que o cliente baixa em separado (requisição GET simples, sem auth). URLs expiram em ~1h.

1. DANFE (PDF) — a NF emitida visualmente

# Pega a URL pré-assinada
DANFE_URL=$(curl -s 'https://api.gubee.com.br/integration/invoicer/invoices/download/danfe/path/60f8a5c2e3b2a87654321098' \
  -H "Authorization: Bearer $JWT")

echo "$DANFE_URL"
# https://storage.gubee.com.br/danfe/60f8a5c2e3b2a87654321098.pdf?X-Amz-Signature=...

# Baixa o arquivo
curl -s "$DANFE_URL" -o danfe-60f8a5c2.pdf

2. NF qualquer (URL legacy)

Para NFs emitidas por qualquer fluxo (não só pelo invoicer novo):

URL=$(curl -s "https://api.gubee.com.br/integration/invoices/download/60f8a5c2e3b2a87654321098" \
  -H "Authorization: Bearer $JWT")

# $URL é a presigned URL pra baixar o XML ou PDF (depende do que o seller config)
curl -s "$URL" -o nf-60f8a5c2.xml

3. Carta de Correção (PDF ou XML)

# PDF
curl -s 'https://api.gubee.com.br/integration/invoicer/invoices/download/correction-letter/60f8a5c2e3b2a87654321098?type=PDF' \
  -H "Authorization: Bearer $JWT" \
  -o carta-correcao.pdf

# XML
curl -s 'https://api.gubee.com.br/integration/invoicer/invoices/download/correction-letter/60f8a5c2e3b2a87654321098?type=XML' \
  -H "Authorization: Bearer $JWT" \
  -o carta-correcao.xml

type aceita PDF ou XML.

4. Preview de DANFE (antes de emitir)

Retorna o binário PDF direto (sem URL pré-assinada), porque é um preview temporário que não está armazenado:

curl -X POST 'https://api.gubee.com.br/integration/invoicer/invoices/preview-danfe' \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{
    "orderId": "MLB1234567890",
    "items": [
      { "skuId": "sku-uuid-1001-blk", "quantity": 1, "price": 4999.90 }
    ],
    "customer": { "name": "Maria Silva", "email": "maria@exemplo.com" },
    "shippingAddress": { "postalCode": "01310100", "street": "Av. Paulista, 1000" }
  }' \
  -o preview-danfe.pdf

Listar NFs de um pedido

curl -s "https://api.gubee.com.br/integration/invoices/list/ORD-2024-0001" \
  -H "Authorization: Bearer $JWT" | jq

[
  {
    "id": "60f8a5c2e3b2a87654321098",
    "orderId": "ORD-2024-0001",
    "number": "123456",
    "series": "1",
    "model": "55",
    "status": "AUTHORIZED",
    "issueDate": "2024-06-15T14:30:00Z",
    "totalValue": 4999.90,
    "danfeLink": "https://storage.gubee.com.br/...",
    "correctionLetters": []
  }
]

Fluxo típico de emissão + download

1. POST /integration/invoicer/invoices/sale  →  retorna invoiceId
2. (síncrono) SEFAZ autoriza em ~5-30s
3. GET  /integration/invoicer/invoices/{id}  →  status = AUTHORIZED
4. GET  /integration/invoicer/invoices/download/danfe/path/{id}  →  URL presigned
5. GET  (a URL presigned)  →  binário PDF

A SEFAZ pode rejeitar a NF (CFOP inválido, destinatário com problema, etc). Nesses casos o status retorna REJECTED e o campo rejectionReason explica o motivo. Corrija o payload e re-emita.

Integração com ERP

ERPs que já emitem NF (Bling, ContaAzul, SAP, etc) tipicamente não usam /integration/invoicer/invoices/* — eles próprios emitem e só sincronizam o status do pedido via PUT /integration/orders/invoiced/{orderId}.

Nesse cenário, a Gubee só precisa saber: - Que a NF foi emitida (PUT /invoiced com a chave de acesso + DANFE URL) - Onde baixar a DANFE quando o marketplace pedir

Para baixar uma DANFE já emitida pelo ERP: - Use GET /integration/invoices/list/{orderId} para descobrir o invoiceId - Use GET /integration/invoices/download/{invoiceId} para pegar a URL - Baixe a URL

Próximos passos