GET, POST or PUT, which one to use to issue a invoice?

Question

Which should I use when the intention is not to view, save or update the data?

I’m creating an API that makes the issuance of an electronic invoice, I made the complete CRUD for the information of the notes, but now I need to create a feature that transmits the XML to the IF, like:

http://localhost/api/nfes/10/transmite

I thought to use PUT or PATCH, because the request will end up updating the Nfe status from "Pending" to "Authorized" in the database, only that there will be no body in the request... what do you think?

Answer 1

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

Including methods, whether or not specified in a specification, RFC 7231, may vary depending on the application. There may be an API that uses the GET method to generate a new record, POST to delete, etc. But, of course, you can imagine the confusion of documenting and using 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:

1. Using the PATCH method;
2. Create your own resource;

But each with its own peculiarities:

When using the PATCH method to issue the invoice, make sure you never use the same method for anything else; otherwise you will run into problems. The PATCH method is often used for partial updates of a resource. As I said, issuing the note would only change the status of the note and, in a way, it would make sense to issue the note in 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 its status 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 so without worrying whether the note would be issued or not.

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

In this case, I would suggest the second approach: to create an own resource only for the issuance of the invoice:

POST /api/emissoes/ HTTP/1.1

id=1

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

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

But, emphasizing, that you, who is responsible for the project, who knows all the requirements and limitations, should know what is best. No chat, for example, I was asked whether in a endpoint that only accepts GET/POST/PUT, as could be done a partial update that would be done in the PATCH. As it would possibly make less sense to create a endpoint Only to partially update the resource, 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 doesn’t hurt to remember that there are many applications that survive only with GET/POST, because the HTML form is unable to send another type of request.

Note: In fact, if it’s an internal enterprise-wide 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 request: EMIT /nota-fiscal/1 HTTP/1.1. It is just not recommended to use this in public Apis, as not all customers can support custom methods.

Answer 2

You say:

Which should I use when the intention is not to view, save or update the data?

And then at the end of the question it says:

as the request will end by updating the Nfe status from "Pending" to "Authorized" in the database

In view of this, the request will update the status of the note, if we understand what Maniero replied in that question, the ideal method for you is PUT.

That is, 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 PUT for data update is CIELO if you consult that method, it serves similarly to what you are wanting to do and uses PUT also.