Class: Nfe::Resources::InboundProductInvoices

Inherits:
AbstractResource show all
Defined in:
lib/nfe/resources/inbound_product_invoices.rb,
sig/nfe/resources/inbound_product_invoices.rbs

Overview

Inbound supplier NF-e (Nota Fiscal Eletrônica de fornecedor) resource for the :cte host family (+https://api.nfse.io+). Manages automatic NF-e fetch via SEFAZ Distribuição DFe, reads received NF-e documents/events, sends the recipient manifest (Manifestação do Destinatário) and reprocesses webhooks.

This is an inbound/query resource (settings + access-key lookups), not an emission resource: there is no discriminated 202 +Pending+/+Issued+ contract here. The host carries no version segment, so paths embed /v2 literally and #api_version is "".

There are two detail surfaces: the generic webhook-v1 path (+.../inbound/key+) and the recommended webhook-v2 path (+.../inbound/productinvoice/key+, which adds a productInvoices array).

Examples:

Enable auto-fetch and manifest awareness of a received NF-e

client.inbound_product_invoices.enable_auto_fetch(company_id: "co-1")
client.inbound_product_invoices.manifest(company_id: "co-1", access_key: "3524...7890")

Constant Summary collapse

MANIFEST_AWARENESS =

Manifest event type — Ciência da Operação (awareness, default).

Returns:

  • (Integer) 
210_210
MANIFEST_CONFIRMATION =

Manifest event type — Confirmação da Operação (confirmation).

Returns:

  • (Integer) 
210_220
MANIFEST_NOT_PERFORMED =

Manifest event type — Operação não Realizada (operation not performed).

Returns:

  • (Integer) 
210_240

Instance Attribute Summary

Attributes inherited from AbstractResource

#client

Instance Method Summary collapse

Methods inherited from AbstractResource

#build_list_page, #build_multipart_body, #cursor_list_page, #delete, #dig_key, #download, #extract_invoice_id, #full_path, #get, #handle_async_response, #hydrate, #hydrate_list, #initialize, #multipart_part, #page_list_page, #parse_json, #post, #put, #unwrap, #upload_multipart

Constructor Details

This class inherits a constructor from Nfe::Resources::AbstractResource

Instance Method Details

#api_family ⇒ Symbol

Returns:

  • (Symbol) 


38
39
40
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 38

def api_family
  :cte
end

#api_version ⇒ String

The :cte host carries no version segment; /v2 is embedded per path.

Returns:

  • (String) 


43
44
45
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 43

def api_version
  ""
end

#compact(hash) ⇒ Hash[untyped, untyped]

Drop nil values so optional fields are omitted from the body.

Parameters:

  • hash (Hash[untyped, untyped])

Returns:

  • (Hash[untyped, untyped]) 


236
237
238
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 236

def compact(hash)
  hash.compact
end

#company_and_key(company_id, access_key) ⇒ [ String, String ]

Parameters:

  • company_id (String)
  • access_key (String)

Returns:

  • ([ String, String ]) 


210
211
212
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 210

def company_and_key(company_id, access_key)
  [Nfe::IdValidator.company_id(company_id), Nfe::IdValidator.access_key(access_key)]
end

#company_key_event(company_id, access_key, event_key) ⇒ [ String, String, String ]

Parameters:

  • company_id (String)
  • access_key (String)
  • event_key (String)

Returns:

  • ([ String, String, String ]) 


214
215
216
217
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 214

def company_key_event(company_id, access_key, event_key)
  [Nfe::IdValidator.company_id(company_id), Nfe::IdValidator.access_key(access_key),
   Nfe::IdValidator.event_key(event_key)]
end

#disable_auto_fetch(company_id:) ⇒ Nfe::InboundSettings

Disable automatic NF-e distribution fetch for a company.

Parameters:

  • company_id (String)
  • company_id: (String)

Returns:



75
76
77
78
79
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 75

def disable_auto_fetch(company_id:)
  id = Nfe::IdValidator.company_id(company_id)
  response = delete("/v2/companies/#{id}/inbound/productinvoices")
  hydrate(Nfe::InboundSettings, parse_json(response.body))
end

#enable_auto_fetch(company_id:, start_from_nsu: nil, start_from_date: nil, environment_sefaz: nil, automatic_manifesting: nil, webhook_version: nil) ⇒ Nfe::InboundSettings

Enable automatic NF-e distribution fetch for a company.

Parameters:

  • company_id (String)
  • start_from_nsu (Integer, String, nil) (defaults to: nil)
  • start_from_date (String, nil) (defaults to: nil) —

    ISO 8601 starting date.

  • environment_sefaz (String, nil) (defaults to: nil) —

    +"Production"+/+"Test"+.

  • automatic_manifesting (Hash, nil) (defaults to: nil) —

    auto-manifesting config.

  • webhook_version (String, Integer, nil) (defaults to: nil) —

    +"1"+/+"2"+.

  • company_id: (String)
  • start_from_nsu: (Object) (defaults to: nil)
  • start_from_date: (String, nil) (defaults to: nil)
  • environment_sefaz: (String, nil) (defaults to: nil)
  • automatic_manifesting: (Object) (defaults to: nil)
  • webhook_version: (Object) (defaults to: nil)

Returns:



58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 58

def enable_auto_fetch(company_id:, start_from_nsu: nil, start_from_date: nil,
                      environment_sefaz: nil, automatic_manifesting: nil, webhook_version: nil)
  id = Nfe::IdValidator.company_id(company_id)
  body = compact(
    "startFromNsu" => start_from_nsu, "startFromDate" => start_from_date,
    "environmentSEFAZ" => environment_sefaz, "automaticManifesting" => automatic_manifesting,
    "webhookVersion" => webhook_version
  )
  response = post("/v2/companies/#{id}/inbound/productinvoices",
                  body: json_body(body), headers: json_headers)
  hydrate(Nfe::InboundSettings, parse_json(response.body))
end

#get_details(company_id:, access_key:) ⇒ Nfe::InboundInvoiceMetadata

Get details of an inbound document by access key (webhook-v1 format).

Parameters:

  • company_id (String)
  • access_key (String)
  • company_id: (String)
  • access_key: (String)

Returns:



96
97
98
99
100
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 96

def get_details(company_id:, access_key:)
  id, key = company_and_key(company_id, access_key)
  response = get("/v2/companies/#{id}/inbound/#{key}")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#get_event_details(company_id:, access_key:, event_key:) ⇒ Nfe::InboundInvoiceMetadata

Get details of an event related to an inbound document (webhook-v1).

Parameters:

  • company_id (String)
  • access_key (String)
  • event_key (String)
  • company_id: (String)
  • access_key: (String)
  • event_key: (String)

Returns:



120
121
122
123
124
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 120

def get_event_details(company_id:, access_key:, event_key:)
  id, key, ev = company_key_event(company_id, access_key, event_key)
  response = get("/v2/companies/#{id}/inbound/#{key}/events/#{ev}")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#get_event_xml(company_id:, access_key:, event_key:) ⇒ String

Download the XML of an event related to an inbound document.

Parameters:

  • company_id (String)
  • access_key (String)
  • event_key (String)
  • company_id: (String)
  • access_key: (String)
  • event_key: (String)

Returns:

  • (String) —

    raw XML bytes (+ASCII-8BIT+).



154
155
156
157
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 154

def get_event_xml(company_id:, access_key:, event_key:)
  id, key, ev = company_key_event(company_id, access_key, event_key)
  download("/v2/companies/#{id}/inbound/#{key}/events/#{ev}/xml", headers: xml_accept)
end

#get_json(company_id:, access_key:) ⇒ Nfe::InboundInvoiceMetadata

Get the structured JSON representation of an inbound NF-e by access key.

Parameters:

  • company_id (String)
  • access_key (String)
  • company_id: (String)
  • access_key: (String)

Returns:



174
175
176
177
178
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 174

def get_json(company_id:, access_key:)
  id, key = company_and_key(company_id, access_key)
  response = get("/v2/companies/#{id}/inbound/productinvoice/#{key}/json")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#get_pdf(company_id:, access_key:) ⇒ String

Download the PDF (DANFE) of an inbound NF-e by access key.

Parameters:

  • company_id (String)
  • access_key (String)
  • company_id: (String)
  • access_key: (String)

Returns:

  • (String) —

    raw PDF bytes (+ASCII-8BIT+).



164
165
166
167
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 164

def get_pdf(company_id:, access_key:)
  id, key = company_and_key(company_id, access_key)
  download("/v2/companies/#{id}/inbound/#{key}/pdf", headers: pdf_accept)
end

#get_product_invoice_details(company_id:, access_key:) ⇒ Nfe::InboundInvoiceMetadata

Get details of an inbound NF-e by access key (webhook-v2 format, recommended; adds the product_invoices array).

Parameters:

  • company_id (String)
  • access_key (String)
  • company_id: (String)
  • access_key: (String)

Returns:



108
109
110
111
112
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 108

def get_product_invoice_details(company_id:, access_key:)
  id, key = company_and_key(company_id, access_key)
  response = get("/v2/companies/#{id}/inbound/productinvoice/#{key}")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#get_product_invoice_event_details(company_id:, access_key:, event_key:) ⇒ Nfe::InboundInvoiceMetadata

Get details of an event related to an inbound NF-e (webhook-v2).

Parameters:

  • company_id (String)
  • access_key (String)
  • event_key (String)
  • company_id: (String)
  • access_key: (String)
  • event_key: (String)

Returns:



132
133
134
135
136
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 132

def get_product_invoice_event_details(company_id:, access_key:, event_key:)
  id, key, ev = company_key_event(company_id, access_key, event_key)
  response = get("/v2/companies/#{id}/inbound/productinvoice/#{key}/events/#{ev}")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#get_settings(company_id:) ⇒ Nfe::InboundSettings

Get the current automatic NF-e fetch settings.

Parameters:

  • company_id (String)
  • company_id: (String)

Returns:



85
86
87
88
89
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 85

def get_settings(company_id:)
  id = Nfe::IdValidator.company_id(company_id)
  response = get("/v2/companies/#{id}/inbound/productinvoices")
  hydrate(Nfe::InboundSettings, parse_json(response.body))
end

#get_xml(company_id:, access_key:) ⇒ String

Download the XML of an inbound document by access key.

Parameters:

  • company_id (String)
  • access_key (String)
  • company_id: (String)
  • access_key: (String)

Returns:

  • (String) —

    raw XML bytes (+ASCII-8BIT+).



143
144
145
146
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 143

def get_xml(company_id:, access_key:)
  id, key = company_and_key(company_id, access_key)
  download("/v2/companies/#{id}/inbound/#{key}/xml", headers: xml_accept)
end

#json_body(data) ⇒ String

Parameters:

  • data (Object)

Returns:

  • (String) 


223
224
225
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 223

def json_body(data)
  JSON.generate(data)
end

#json_headers ⇒ Hash[String, String]

Returns:

  • (Hash[String, String]) 


219
220
221
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 219

def json_headers
  { "Content-Type" => "application/json" }
end

#manifest(company_id:, access_key:, tp_event: MANIFEST_AWARENESS) ⇒ String

Send the recipient manifest (Manifestação do Destinatário) for an NF-e. tp_event defaults to MANIFEST_AWARENESS (210210); the other codes are MANIFEST_CONFIRMATION (210220) and MANIFEST_NOT_PERFORMED (210240).

Parameters:

  • company_id (String)
  • access_key (String)
  • tp_event (Integer) (defaults to: MANIFEST_AWARENESS)
  • company_id: (String)
  • access_key: (String)
  • tp_event: (Integer) (defaults to: MANIFEST_AWARENESS)

Returns:

  • (String) —

    the manifest response body.



188
189
190
191
192
193
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 188

def manifest(company_id:, access_key:, tp_event: MANIFEST_AWARENESS)
  id, key = company_and_key(company_id, access_key)
  response = post("/v2/companies/#{id}/inbound/#{key}/manifest",
                  query: { tpEvent: tp_event })
  response.body || ""
end

#pdf_accept ⇒ Hash[String, String]

Returns:

  • (Hash[String, String]) 


231
232
233
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 231

def pdf_accept
  { "Accept" => "application/pdf" }
end

#reprocess_webhook(company_id:, access_key_or_nsu:) ⇒ Nfe::InboundInvoiceMetadata

Reprocess the webhook for an inbound NF-e, identified by either a 44-digit access key OR a numeric NSU. A bare NSU is not rejected as an invalid key.

Parameters:

  • company_id (String)
  • access_key_or_nsu (String, Integer)
  • company_id: (String)
  • access_key_or_nsu: (Object)

Returns:



201
202
203
204
205
206
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 201

def reprocess_webhook(company_id:, access_key_or_nsu:)
  id = Nfe::IdValidator.company_id(company_id)
  identifier = Nfe::IdValidator.presence!(access_key_or_nsu, "access_key_or_nsu")
  response = post("/v2/companies/#{id}/inbound/productinvoice/#{identifier}/processwebhook")
  hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
end

#xml_accept ⇒ Hash[String, String]

Returns:

  • (Hash[String, String]) 


227
228
229
 
# File 'lib/nfe/resources/inbound_product_invoices.rb', line 227

def xml_accept
  { "Accept" => "application/xml" }
end