Ajustamos a descrição sobre limitação de items no endpoint Criar Fatura
A antiga descrição informava sobre o limite de 30 itens, porém, não deixava claro que esta limitação está presente apenas em ambiente de testes.
Deste modo, a descrição atual é: "Itens da fatura. O parâmetro price_cents tem o valor mínimo de 100. Limite de 30 itens em test_mode. Já live_modenão há limites."
Percebemos uma oportunidade de otimizar a organização e a clareza das tabelas que informam os padrões para preenchimento do nome e código do banco, além dos números de agência e conta. Com essa atualização, buscamos facilitar a consulta e a integração dos dados bancários.
As alterações foram aplicadas nas seguintes referências:
Anteriormente a Endpoint informava que as faturas não poderiam ser canceladas com o status expirada. Atualizada para: Os status possíveis para cancelamento: Em análise, pendente e expirada.
Endpoints atualizados
Os endpoints que receberam esta atualização foram:
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.
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.
Anteriormente, a funcionalidade de Splits era limitada ao endpoint de criação de faturas (POST /v1/invoices), permitindo regras variáveis de Split apenas nesse contexto. Com a nova atualização, o Split por Assinaturas foi introduzido, ampliando as possibilidades para usuários que utilizam o endpoint de criação de assinaturas (POST /v1/subscriptions). Essa melhoria permite a configuração direta do objeto splits durante a criação de uma assinatura.
O que muda na prática?
Agora, ao criar uma assinatura, é possível definir regras personalizadas de divisão de valores (Split) diretamente no momento da requisição. Isso oferece maior flexibilidade e automação na gestão de receitas, especialmente para negócios que dependem de repasses para diferentes contas.
Assim, as mesmas possibilidades já existentes para faturas estão disponíveis para assinaturas, promovendo um alinhamento entre as duas funcionalidades.
Exemplo de Requisição
Veja abaixo um exemplo prático de como configurar um Split durante a criação de uma assinatura:
Quantidade em centavos que será direcionada para essa conta
Importante ⚠️
Ao incluir regras de Split diretamente no payload da requisição de criação de assinaturas, as regras globais de Split configuradas na conta serão ignoradas. Nesse caso, as regras definidas no objeto splits prevalecerão.
Certifique-se de revisar a lógica de divisão antes de implementar essa funcionalidade para garantir que ela atenda às suas necessidades específicas.
Essa novidade traz mais flexibilidade para adaptar os processos de divisão de receitas às exigências do seu modelo de negócio!
O parâmetro address_proof foi adicionado na Verificação de Subcontas!
A partir de agora, a verificação de subcontas exige um terceiro documento como parte do processo. Além dos parâmetros já existentes, identification e selfie, também será necessário enviar o parâmetro address_proof. Isso implica que a solicitação de verificação deve conter três arquivos obrigatórios.
Essa alteração impacta o endpoint: POST /v1/accounts/{account_id}/request_verification
Obrigatoriedade dos Arquivos: Os três arquivos (identification, selfie e address_proof) são estritamente necessários para que a verificação seja processada. Qualquer ausência ou formato incorreto resultará em falha na solicitação.
Formato dos Arquivos: Certifique-se de que os documentos enviados estejam codificados em Base64 e atendam aos critérios de qualidade e legibilidade.
Essa atualização busca reforçar a segurança e a conformidade regulatória no processo de verificação de subcontas, garantindo maior proteção para os usuários e seus negócios.
