NFC-e pelo ERP externo

Quando a organização escolhe "Pelo ERP externo" em Configurações → Operação → Emissão da NFC-e, a ETech não emite a NFC-e de nenhuma venda dela, em canal nenhum. O ERP externo emite a partir dos eventos do Webhook de venda e manda a nota por e-mail quando o consumidor pede.

Como funciona

A venda é concluída, e o sale.completed chega com invoice.issuer igual a ExternalErp. É a ordem de emitir.
O ERP externo emite a NFC-e com os itens e os pagamentos do evento.
Quando o consumidor pede a nota por e-mail, na máquina, no PDV, no SmartPOS ou pelo painel, chega o sale.receipt_requested com o endereço.
Opcional: o ERP externo devolve à ETech a chave e o link da nota, e o painel passa a mostrá-la.
Se a venda for estornada, chega o sale.canceled, e o ERP externo cancela a nota.

A opção exige o webhook de venda. Sem ele configurado, a ETech recusa a escolha.
Vale para todos os canais. O webhook passa a levar as vendas da organização em qualquer canal, não só as de vending. O data.channel diz de onde a venda veio.
O emissor fica gravado na venda. Uma venda concluída antes de uma troca de emissor mantém o que tinha. Emita só as que chegam com invoice.issuer igual a ExternalErp.
O sale.invoice_issued não chega para essas vendas. Ele é da nota emitida pela ETech.

A ordem de emitir

A venda com status igual a Completed e invoice.issuer igual a ExternalErp é a ordem de emitir. Os campos que importam à nota, no data do evento:

{
  "saleId": 98765,
  "status": "Completed",
  "channel": "VendingMachine",
  "company": { "document": "12345678000190" },
  "customer": { "document": "12345678909" },
  "items": [
    { "skuId": 555, "ean": "7891234567895", "description": "Cerveja IPA 473 ml",
      "quantity": 2, "unitPrice": 10.9, "discount": 0, "total": 21.8 }
  ],
  "payments": [
    { "method": "Crédito", "amount": 21.8, "brand": null, "nsu": "000123456", "authorizationCode": "A1B2C3",
      "type": "CreditCard", "interface": "Tef", "acquirerDocument": "10440482000154" }
  ],
  "invoice": {
    "issuer": "ExternalErp", "email": null,
    "number": null, "serie": null, "key": null, "status": null,
    "externalKey": null, "externalUrl": null
  }
}

Todos os itens pagos entram na nota, inclusive a unidade que a máquina não entregou: ela foi cobrada.
Uma nota por venda. O webhook entrega pelo menos uma vez: emita uma vez só por saleId.
Todo evento traz a venda inteira. A ordem de chegada não é garantida, e o sale.receipt_requested pode chegar antes do sale.completed: emita pelo primeiro que chegar.
O cadastro fiscal é do ERP externo. NCM, CFOP e tributação saem do catálogo dele, pelo ean do item.
O customer é nulo quando o consumidor não se identificou.

O grupo de pagamento

Campo	O que é
`type`	O tipo do meio de pagamento, que define a forma de pagamento da nota: `Cash`, `CreditCard`, `DebitCard`, `Pix`, `BankTransference` e outros
`amount`	O valor pago nesse meio
`interface`	Como o pagamento foi capturado: `Tef`, `Pos`, `Manual` ou `Online`. A máquina usa sempre `Tef`
`acquirerDocument`	O CNPJ da credenciadora, só dígitos. Vem nos pagamentos de cartão, Pix e transferência com NSU
`brand`	A bandeira do cartão. Nula nas vendas da máquina até o app passar a capturá-la
`authorizationCode`	O código de autorização da transação
`nsu`	O NSU da transação

O pedido de e-mail

O sale.receipt_requested é a ordem de mandar a nota por e-mail. O endereço vem em invoice.email.

Pode chegar antes de a nota existir. Guarde o pedido e mande o e-mail quando a nota for autorizada.
Pode vir mais de um pedido para a mesma venda, com o mesmo e-mail ou outro. Mande para o invoice.email de cada evento.
Marque o evento no cadastro do webhook, se lá houver eventos marcados. No painel ele aparece como "Nota pedida por e-mail".

O cancelamento

O sale.canceled de uma venda com invoice.issuer igual a ExternalErp pede o cancelamento da nota.

O prazo para cancelar a NFC-e é curto e varia por UF. Processe o evento assim que ele chegar.
Se a nota ainda não foi emitida, não emita.

Devolver a nota (opcional)

O ERP externo pode devolver a chave e o link da nota que emitiu. O painel passa a mostrá-los no detalhe da venda, e a consulta de venda e os eventos seguintes os trazem em invoice.externalKey e invoice.externalUrl.

PUT /integration/v1/sales/98765/invoice
x-api-key: <api key>
Authorization: Bearer <access_token>
User-Agent: <nome-do-sistema>/<versão>
Content-Type: application/json

{ "key": "<chave de acesso, 44 dígitos>", "url": "<link de consulta>" }

key é a chave de acesso, com 44 dígitos.
url é opcional: o link de consulta ou do DANFE, em https.
Chamar de novo substitui a chave e o link anteriores.
A resposta de sucesso é 204, sem corpo.

HTTP	Código	Quando
400	`INTEGRATION.INVOICE_KEY_INVALID`	Chave ausente ou sem 44 dígitos
400	`INTEGRATION.INVOICE_URL_INVALID`	`url` que não é `https`
404	`INTEGRATION.SALE_NOT_FOUND`	Venda de outra organização, ou com a nota de outro emissor

Os erros de token, credencial e gateway estão em Acesso.

Como funciona​

A ordem de emitir​

O grupo de pagamento​

O pedido de e-mail​

O cancelamento​

Devolver a nota (opcional)​