issue_invoice
Issue a Brazilian fiscal document: NFS-e or NF-e.
This produces a legal fiscal document. Confirm the data with the user before calling when you inferred any field.
Every item needs a price: unit_price is what one unit costs and amount is the line's gross total. Send unit_price with quantity when the user quotes a price per unit, amount when they quote the line. Sending both asserts they agree and is refused if they do not.
document_type nfse is a service invoice: each item needs a description and a price, the recipient address is optional, and service_code (LC 116/2003 item.subitem) falls back to the company's fiscal profile when omitted.
document_type nfe is for goods, and the SEFAZ rejects a partial one: every item needs ncm and cfop, and recipient_address is required with street, number, neighborhood, city, state, zip_code and city_code all filled. Call validate_invoice_payload first when any of that was inferred rather than given.
Pass idempotency_key when a retry is possible: repeating the same key with the same payload replays the first answer instead of issuing a second document. Without one, a retry after a lost response issues again — another credit, another number burned, and undoing it means cancelling, which has a deadline. Nothing generates the key for you; use one per business event, not per call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| number | No | ||
| series | No | ||
| tax_id | Yes | ||
| client_name | Yes | ||
| document_type | Yes | ||
| idempotency_key | No | ||
| recipient_address | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Local id. Use it for reissue and for submissions, and when a document was rejected and has no key. | |
| status | No | issued, rejected or cancelled. | |
| protocol | No | The authorization protocol, when granted. | |
| access_key | No | The authorizer's key. Absent while the document is not authorized. |