10/12/24 — +2 novos endpoints

Agora é possível buscar Faturas através do `external_reference`, `order_id` ou `end_to_end`!

Anteriormente, para consultar uma fatura na iugu, o dado principal utilizado era o invoice_id. No entanto, em diversas situações, esse identificador não era armazenado pelos nossos clientes, dificultando a consulta direta. Agora, com os novos endpoints, é possível realizar buscas utilizando outros parâmetros, como:

external_reference: Referência externa configurada no momento da criação da fatura.
order_id: Identificador do pedido atribuído durante a criação da fatura.
end_to_end: Código específico para transações realizadas ou reembolsadas via PIX.

Essa funcionalidade visa proporcionar maior flexibilidade e assertividade na localização de faturas.

Referências de Endpoints

Descrição	Endpoint
Buscar Fatura por IDs externos	`GET` `/v1/resource_search`
Buscar Fatura por ID Externos de Subcontas	`GET` `/v1/marketplace_resource_search`

Importante ⚠️

Para utilizar esses endpoints, é necessário especificar o tipo de parâmetro no campo query_field e informar o valor correspondente em value.
Veja abaixo as opções disponíveis:

Parâmetro	Descrição
`external_id`	Para buscar faturas que possuem um valor específico configurado no campo `external_reference` durante a criação.
`order_id`	Para localizar faturas utilizando o valor atribuído no parâmetro `order_id` no momento de sua criação.
`end_to_end`	Para identificar faturas pagas ou reembolsadas via PIX, utilizando o código único de transação `end_to_end` fornecido pelo Banco Central.

Exemplo de Requisição - `external_reference`

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=external_id&value=meu-external-id&api_token=seu-api_token' \
     --header 'accept: application/json'

query_field: Deve conter o valor external_id.
value: Insira o identificador externo configurado na fatura.

Exemplo de Requisição - `order_id`

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=order_id&value=meu-order_id&api_token=seu-api_token' \
     --header 'accept: application/json'

query_field: Deve conter o valor order_id.
value: Insira o identificador de pedido configurado na fatura.

Exemplo de Requisição - `end_to_end`

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=end_to_end&value=id-do-end_to_end&api_token=seu-api_token' \
     --header 'accept: application/json'

query_field: Deve conter o valor end_to_end.
value: Insira o código único da transação PIX.

Benefícios

Assertividade: Localize faturas com maior precisão utilizando identificadores alternativos.
Flexibilidade: Facilita o rastreamento mesmo quando o invoice_id não é salvo ou está indisponível.
Suporte PIX: Inclui a busca por transações realizadas via PIX, refletindo as demandas atuais do mercado.

Essa melhoria torna o gerenciamento de faturas mais eficiente e alinhado às necessidades de diferentes cenários operacionais.

Agora é possível buscar Faturas através do external_reference, order_id ou end_to_end!