API Standard

Gere a chave em Conta › Integrações. Ela aparece uma vez só. Envie a chave em todo pedido no cabeçalho X-Optima-Key. Também aceitamos Authorization: Bearer com a mesma chave.

A chave fica no servidor do ERP. Nunca coloque a chave no navegador nem em aplicativo de celular. O plano da empresa é conferido em toda chamada: se a conta sair do Pro, a chave para de funcionar até a empresa voltar.

POST /doacoes. O cabeçalho Idempotency-Key é obrigatório, com 8 caracteres ou mais: se a rede cair e você enviar de novo com a mesma chave e o mesmo conteúdo, a doação não duplica e a resposta devolve a doação já criada.

curl -X POST "https://edmunmfpzvbjzcocncdf.supabase.co/functions/v1/erp-standard-api/api/v1/doacoes" \
  -H "X-Optima-Key: SUA_CHAVE" \
  -H "Idempotency-Key: ERP-TRX-0001" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"ERP-TRX-0001","product_name":"Arroz 5kg","tipo_embalagem":"embalado","product_expiration_date":"2027-01-14","expiration_date":"2026-10-30","quantity":100,"unit_weight":5,"unit_type":"kg","estimated_value":2500}'

{
  "ok": true,
  "donation_id": "d6b2c1e0-0000-4000-8000-0000000041f0",
  "status": "available",
  "trace_id": "3b1f0c2a-0000-4000-8000-00000000a92c",
  "created_at": "2026-10-14T17:32:08Z"
}

As datas do exemplo andam com o dia, para o exemplo nunca nascer vencido.

Toda resposta é JSON com ok. No envio aceito, 201 com o id da doação, a situação (available, disponível no mural) e um código de rastreio. Quando a doação não passa nas regras, 400 com a lista erros: cada item diz o campo, o problema e como corrigir.

{
  "ok": false,
  "error": "product_expiration_date (validade impressa) é obrigatória para produto embalado.",
  "erros": [
    {
      "campo": "product_expiration_date",
      "mensagem": "product_expiration_date (validade impressa) é obrigatória para produto embalado.",
      "como_corrigir": "Envie a validade impressa na embalagem no formato AAAA-MM-DD. Se o produto não for embalado, informe tipo_embalagem in_natura ou preparado."
    }
  ]
}

Até 120 chamadas por minuto por chave, contando todas as rotas. Para testar sem publicar no mural, envie para POST /doacoes/teste: a API confere tudo com as mesmas regras e responde 200 quando a doação passaria, ou 400 com a lista de erros, sem criar a doação. No painel, o botão "Enviar doação de teste" em Conta › Integrações faz o mesmo sem colar a chave.

curl -X POST "https://edmunmfpzvbjzcocncdf.supabase.co/functions/v1/erp-standard-api/api/v1/doacoes/teste" \
  -H "X-Optima-Key: SUA_CHAVE" \
  -H "Idempotency-Key: ERP-TRX-0001" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"ERP-TRX-0001","product_name":"Arroz 5kg","tipo_embalagem":"embalado","product_expiration_date":"2027-01-14","expiration_date":"2026-10-30","quantity":100,"unit_weight":5,"unit_type":"kg","estimated_value":2500}'

• POST /doacoesEnvia uma doação. Ela entra no mural das ONGs da região como qualquer doação feita na tela.
• POST /doacoes/testeConfere a doação com as mesmas regras do envio e não grava nada.
• GET /doacoes/{donation_id}Situação de uma doação enviada pela API. Também aceita /doacoes/?external_id=SEU_ID.

Situação da doação: available, requested, confirmed, received ou cancelled. A consulta só encontra doações da empresa dona da chave.