Idempotência

A Linka API usa idempotência para prevenir cobranças duplicadas causadas por retries de rede, timeouts ou bugs no cliente.

Como funciona

Envie o header Idempotency-Key com um valor único por operação (UUID v4 recomendado; aceita letras, números, - e _, até 128 caracteres):

curl -X POST https://api.linkagateway.com/api/v1/cobranca/transactions \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "paymentMethod": "PIX", ...}'

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_live_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
  },
  body: JSON.stringify({
    amount: 1000,
    paymentMethod: 'PIX',
  }),
});

const { data: transaction } = await response.json();

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_live_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
  },
  body: JSON.stringify({
    amount: 1000,
    paymentMethod: 'PIX',
  }),
});

const { data: transaction } = await response.json();

import requests

response = requests.post(
    'https://api.linkagateway.com/api/v1/cobranca/transactions',
    headers={
        'x-api-key': 'sk_live_...',
        'Content-Type': 'application/json',
        'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
    },
    json={
        'amount': 1000,
        'paymentMethod': 'PIX',
    },
)

transaction = response.json()['data']

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"amount":        1000,
		"paymentMethod": "PIX",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.linkagateway.com/api/v1/cobranca/transactions", bytes.NewReader(body))
	req.Header.Set("x-api-key", "sk_live_...")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "550e8400-e29b-41d4-a716-446655440000")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

Comportamento

Cenário	Resultado
Primeira requisição com a key	Processa normalmente e armazena o resultado
Requisição repetida com mesma key e mesmo body	Retorna a resposta original (mesmo status HTTP), sem reprocessar
Mesma key com body diferente	`422` — código `IDEMPOTENCY_KEY_CONFLICT`
Mesma key com a requisição original ainda em processamento	`409` — código `IDEMPOTENCY_IN_FLIGHT`, com header `Retry-After: 5`
Header ausente em endpoint que o exige	`400` — código `IDEMPOTENCY_KEY_MISSING`
Formato inválido ou key com mais de 128 caracteres	`400` — `IDEMPOTENCY_KEY_INVALID_FORMAT` / `IDEMPOTENCY_KEY_TOO_LONG`

Endpoints que exigem Idempotency-Key

Endpoint	Obrigatório
`POST /api/v1/cobranca/transactions`	Sim
`POST /api/v1/cobranca/withdrawals`	Sim
`POST /v1/disputes/appeal`	Sim
`POST /v1/disputes/{id}/generate-file-urls`	Sim

Duração

A duração varia por endpoint, pois POST /api/v1/cobranca/transactions é servido por um serviço diferente dos demais:

Endpoint	Duração
`POST /api/v1/cobranca/transactions`	24 horas
`POST /api/v1/cobranca/withdrawals`, `POST /v1/disputes/appeal`, `POST /v1/disputes/{id}/generate-file-urls`	72 horas

Após o período correspondente, a mesma key pode ser reutilizada como uma nova operação.

Boas Práticas

Use UUID v4

Gere UUIDs v4 aleatórios para cada operação. Não use IDs sequenciais ou valores previsíveis.

Associe a key ao pedido

Use o mesmo Idempotency-Key para retries da mesma operação. Gere um novo para cada operação distinta.

Retry com a mesma key

Se receber timeout ou erro de rede, repita a requisição com o mesmo Idempotency-Key. Isso garante que o pagamento não será duplicado.

Respeite o Retry-After

Ao receber 409 IDEMPOTENCY_IN_FLIGHT, aguarde o valor do header Retry-After (em segundos) antes de repetir.

Exemplo de retry seguro

async function createTransaction(payload, idempotencyKey, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions', {
        method: 'POST',
        headers: {
          'x-api-key': 'sk_live_...',
          'Idempotency-Key': idempotencyKey, // mesma key em todos os retries
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });
      if (response.status === 409) {
        const retryAfter = Number(response.headers.get('Retry-After') ?? 5);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      const { data } = await response.json();
      return data;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * (attempt + 1))); // backoff
    }
  }
}

Visao Geral

Onboarding

Guias

Referencia

Como funciona

Comportamento

Endpoints que exigem Idempotency-Key

Duração

Boas Práticas

Exemplo de retry seguro

​Como funciona

​Comportamento

​Endpoints que exigem Idempotency-Key

​Duração

​Boas Práticas

​Exemplo de retry seguro

Como funciona

Comportamento

Endpoints que exigem Idempotency-Key

Duração

Boas Práticas

Exemplo de retry seguro