📘

O que você vai aprender com este artigo?

• Conceito de idempotência e sua importância em APIs
• Como a iugu implementa a idempotência para evitar duplicidade de requisições
• Passo a passo para utilizar a chave de idempotência nos headers das requisições
• Exemplos de uso da chave de idempotência para criação de faturas e outras operações

O que é Idempotência

A idempotência em uma API consiste no envio de várias requisições idênticas num curto espaço de tempo, em que uma única requisição é executada com sucesso. Isso significa que, se por algum problema de rede ou outros fatores, na hora de enviar uma requisição para a API essa chamada for enviada mais de uma vez, apenas uma requisição será processada.

Supondo que um ecommerce enviou uma requisição de criação de fatura, mas nesse momento ocorreu um problema de rede e a requisição foi enviada duas vezes com os mesmos dados e no mesmo instante. Utilizando a chave de idempotência apenas uma das requisições seria processada e isso não geraria um pedido duplicado.

Como usar chave de idempotência

A chave de idempotência é criada pelo próprio lojista e deve ser enviada no header da requisição no parâmetro chamado Idempotency-Key. A API iugu aceita a chave nas chamadas de Criar fatura, Criar assinatura, Transferência para Terceiros, Criar Pedido de Pagamento, Criar cliente e realizar Cobrança direta.

Se ocorrer várias requisições com a mesma informação no mesmo instante, uma delas será processada com sucesso e se outra requisição for enviada com a mesma chave, será retornado o erro 409.

Exemplo de criação de fatura com chave de idempotência

curl --location --request POST 'https://api.iugu.com/v1/invoices' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Idempotency-Key: my_key00000001' \ 
--header 'Cookie: __cfruid=9b2d63b8222c0e9be8d996bf72b2900f41d43872-1636034578' \ 
--data-raw '{ 
    "email": "[email protected]", 
    "due_date": "2021-12-10", 
    "ensure_workday_due_date": false, 
    "items": [ 
        { 
            "description": "Item teste", 
            "quantity": 1, 
            "price_cents": 1000 
        } 
    ], 
     "payable_with": [ 
        "all" 
    ], 
    "payer": { 
        "cpf_cnpj": "56081236030", 
        "name": "Customer da Silva", 
        "phone_prefix": "11", 
        "phone": "988776655", 
        "email": "[email protected]", 
        "address": { 
            "zip_code": "04578000", 
            "street": "Av. das Nações Unidas", 
            "number": "12495 ", 
            "district": "Cidade Monções", 
            "city": "São Paulo", 
            "state": "SP", 
            "country": "Brasil", 
            "complement": "17 andar" 
        } 
    } 
}'

Modelo de response (sucesso)

Modelo de response (erro)