Envio em lote e idempotência

Como enviar dados ao BIX em lotes, ler o resultado de cada item e repetir uma chamada sem gravar duas vezes.

Todo envio da API pública (POST) funciona do mesmo jeito: um lote de itens, processados um a um, com um resultado por item.

O formato

{
  "items": [
    {"internal_code": "1001", "ean": "7891234567890", "description": "ARROZ TIPO 1 5KG"},
    {"internal_code": "1002", "ean": "7891234567906", "description": "FEIJÃO CARIOCA 1KG"}
  ]
}

Até 500 itens por chamada. Acima disso, a chamada inteira é recusada com 400 invalid_parameter. Divida em vários lotes.
Cada item é criado ou atualizado pela chave do recurso (o guia de cada um diz qual é).
Campo fora do contrato é recusado no item, com o nome do campo no detail: é o que pega um pirce digitado no lugar de price antes que ele vire dado errado.

A resposta

A chamada responde 200 sempre que o lote foi processado, mesmo que alguns itens tenham sido recusados. O que aconteceu com cada um está em results, na mesma ordem de items:

{
  "summary": {"total": 3, "created": 1, "updated": 1, "skipped": 0, "errors": 1},
  "results": [
    {"index": 0, "status": "created", "id": 346, "code": null, "detail": null},
    {"index": 1, "status": "updated", "id": 345, "code": null, "detail": null},
    {"index": 2, "status": "error", "id": null, "code": "invalid_parameter",
     "detail": "Campo obrigatório ausente: ean."}
  ]
}

`status`	Significa
`created`	O item não existia e foi criado
`updated`	O item existia e foi atualizado
`skipped`	Nada a fazer (por exemplo, `update_only` sem registro)
`error`	Recusado: veja `code` e `detail`. Os outros itens do lote não são afetados

Confira os erros

Um 200 não quer dizer que tudo entrou. Percorra results e registre os itens com status: error do seu lado: eles não foram gravados.

Idempotência: repetir sem gravar duas vezes

Uma chamada pode dar timeout ou cair a rede depois de o BIX ter gravado. Repetir às cegas grava de novo. Para repetir com segurança, mande o cabeçalho Idempotency-Key:

curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/products" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c8e2a-3b7d-4c51-9a0e-2d4f8b7c1e90" \
  -d @lote-001.json

Situação	O que o BIX faz
Chave nova	Processa e guarda a resposta por 24 horas
Mesma chave, mesmo corpo	Devolve a resposta guardada, sem gravar de novo, com o cabeçalho `Idempotent-Replayed: true`
Mesma chave, outro corpo	Recusa com `409` `idempotency_key_reused`

A receita:

Gere uma chave nova (um UUID, por exemplo) para cada lote diferente.
Guarde a chave junto com o lote até ter a resposta.
Deu timeout ou erro de rede? Repita o mesmo lote com a mesma chave.

A chave vale por credencial: duas chaves de API diferentes nunca colidem.

Volume

Com 500 itens por chamada e o limite de 120 chamadas por minuto por chave, uma carga completa de dezenas de milhares de itens leva poucos minutos. Mande os lotes em sequência, não em paralelo: o paralelismo não acelera e consome o limite mais rápido. Ver Erros e limites.