GET, POST or PUT, which one to use for issuing an invoice?

Determining which method to use in each situation is always a delicate discussion. The implementation must conform to the needs and limitations of the project.

Including methods, even provided for in a specification, RFC 7231 , may vary by application. There may be an API that uses the GET method to generate a new record, POST to delete, etc. But obviously, imagine the mess that would be to document and use this API? The less strange behaviors your application has, the easier it will be to use it.

Without knowing the details of your project, only with what was detailed in the question, I see two possible solutions:

But each one with its peculiarities:

When using the PATCH method to issue the invoice, make sure you never use the same method for anything else; otherwise you will encounter problems. The PATCH method is often used for partial updates of a resource. As well as said, the issue of the note would change only the status of the note and, in a sense, it would make sense to issue the issue in the PATCH. But what if you need to change other fields of the invoice? One way would be for you to issue the note only when the status of the note is changed from any value to issued - and, please, use transactions here. So if it were to change any other field, such as the NCM of a product, if necessary, you could do it without worrying whether the note would be issued or not.

But I see a possible problem with this approach: what if for some reason an invoice is issued manually and you just want to change the status to issued? If you set the status to be issued, your system will try to issue it again - you can even handle the duplicate feedback of the note and ignore the error, but it is a strange behavior for a system to try to issue a note already issued. Someone from outside, who did not participate in the system project, trying to update the status would not expect the note to be issued - it wants to partially change the feature, just not to issue it.

In this case, I would suggest the second approach: create an own resource just for the invoice issue:

POST /api/emissoes/ HTTP/1.1

id=1

In this way, you could use the POST method to create a new issue and thus leave it open for possible / likely future implementations of an emissions history. You can create a table in the database where you store the invoice issued and the return obtained from SEFAZ. With the GET method, you can get the return of a given issue or a list of multiple issues to generate reports.

Not to mention that you could use the PATCH method to issue correction letters and DELETE for cancellation of notes, for example.

But, stressing that you, who is responsible for the project, who knows all the requirements and limitations, you should know what is best. In the chat , for example, I was asked if in an endpoint that only accepts GET / POST / PUT, how could a partial update be done in PATCH. As it would make less sense to create an endpoint only to partially update the feature, I suggested using the PUT itself, with an additional parameter indicating whether the update should be partial or not. It is not always the best solution, but for the problem presented, it seems to be.

And it's easy to remember that there are many applications that only survive with GET / POST because the HTML form is unable to send another type of request.

  

Note: In fact, if it is an internal-use API, nothing prevents you from creating custom HTTP methods - as long as the environment is properly configured. For example, you could create a method called EMIT and make the request: EMIT /nota-fiscal/1 HTTP/1.1 . It is not recommended to use this in public APIs since not all clients can support custom methods.

You say:

  

What should I use when the intent is not to view, save, and update data?

And then at the end of the question says:

  

Because the request will end up updating the NFe status from "Pending" to "Authorized" in the database

With this in mind, the request will update the status of the note if we understand what Maniero has answered in this question , the ideal method for you is PUT .

  

That is, the PUT should be used in more specific situations where you want to send information and do nothing but store it in some way.

An API that uses the PUT for data refresh is CIELO, if you refer to this method , it serves similarly to what you are trying to do and uses PUT as well.