Overview
'Invoices (NF-e): you send the XML, marketapi validates it and sends it to the marketplace.'
marketapi does not issue invoices (NF-e). You send the already authorized XML, marketapi validates it and sends it to the marketplace in a job. On many marketplaces the invoice blocks shipping, so it comes before the label.
The whole journey: The order lifecycle.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/orders/{orderId}/invoices | List order invoices |
POST | /v1/orders/{orderId}/invoices | Send invoice |
GET | /v1/invoices/{invoiceId} | Get invoice |
GET | /v1/invoices/{invoiceId}/xml | Download invoice XML |
Flow
- Upload the XML as a
confidentialasset. - Call Send invoice with the
xmlAssetId. The invoice is bornpending, and so is the orderinvoiceStatus. - The
invoice.submitjob sends it to the marketplace. The invoice moves tosubmitted. - The marketplace answers:
acceptedorrejected. The webhook arrives, and the order changes with it.
Validation
Before creating the job, marketapi checks the XML. If it fails, the answer is 422 with details.reason, and nothing is saved: invoice_xml_invalid, invoice_not_authorized, invoice_access_key_invalid, invoice_issuer_mismatch or invoice_total_mismatch.
Other refusals are 409: repeated key, cancelled order, or an invoice that was not rejected already exists. To replace a rejected one, send replacesInvoiceId.
States
status | Meaning |
|---|---|
pending | validated, not sent yet |
submitted | sent, waiting for the marketplace |
accepted | accepted |
rejected | rejected; see statusReasons |
Webhooks
invoice.accepted and invoice.rejected. They do not carry the issuer tax ID.
Legal custody of the XML is yours, as issuer. marketapi keeps a confidential copy for the order retention period.