Logo da Plataforma Yep
API REST · Plataforma Yep Documentação técnica para integrações homologadas
Pedidos › Estornos

Estornos (Creditmemo)

Endpoint de /api2/creditmemo para criar credit memo de refund a partir de uma invoice ou de um pedido. Suporta refund online (aciona o método de pagamento) ou offline (apenas registra o estorno), com ajustes de frete e diferenças positivas/negativas.

REST JSON Bearer Token Novo em 2026

Visão geral

Credit memo é a etapa final do ciclo financeiro do pedido. Esta página cobre a criação do estorno; listagem e consulta detalhada de credit memos ainda não estão disponíveis nesta versão (ver Roadmap). Para regras gerais (paginação, datas, status HTTP, tratamento de items), consulte a página principal de Pedidos.

2
Tipos de refundonline e offline (padrão).
4
Origens aceitasinvoice_id, invoice_increment_id, order_id, order_increment_id.
2x
Aliases/api2/creditmemo e /api2/creditmemo/create.
3
Ajustesshipping_amount, adjustment_positive, adjustment_negative.
POST/api2/creditmemo

Criar credit memo para refund. Por segurança, refund_type padrão é offline — use online apenas quando quiser acionar o método de pagamento.

EstornoRefund
invoice_id / invoice_increment_id / order_id / order_increment_id
Identifique a origem com exatamente um destes campos.
refund_type Opcional
Aceita online ou offline. Padrão offline.
items Opcional
Lista de itens a estornar. Se omitido, estorna as quantidades disponíveis.
shipping_amount Opcional
Valor de frete a estornar (numérico, em moeda da loja).
adjustment_positive Opcional
Crédito adicional ao cliente (numérico).
adjustment_negative Opcional
Débito a descontar do estorno (numérico, ex.: taxa de cancelamento).
send_email Opcional
Quando true, envia o e-mail do credit memo após salvar.
comment Opcional
Comentário registrado no credit memo.

Estorno por invoice

POST /api2/creditmemo
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_id": 456,
  "refund_type": "offline",
  "send_email": true,
  "comment": "Estorno criado pela integração."
}

Estorno parcial por pedido

POST /api2/creditmemo/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "refund_type": "offline",
  "shipping_amount": 0,
  "adjustment_positive": 0,
  "adjustment_negative": 0,
  "items": [
    {"order_item_id": 10, "qty": 1}
  ]
}

Estorno online com itens e ajuste

POST /api2/creditmemo
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_increment_id": "100000045",
  "refund_type": "online",
  "shipping_amount": 19.90,
  "adjustment_negative": 5.00,
  "items": [
    {"sku": "PRODUTO-001", "qty": 1}
  ],
  "send_email": true,
  "comment": "Refund parcial após devolução."
}

Atenção

Credit memos não podem ser revertidos após a criação. Quando refund_type=online, o sucesso depende do método de pagamento suportar estorno online; caso contrário, a integração de pagamento retornará erro nativo.

Aceita também o alias POST /api2/creditmemo/create.

Formas de uso suportadas

Combinações testadas e homologadas para o recurso Creditmemo.

Estorno total offline por invoicePOST /api2/creditmemo + invoice_id + refund_type=offline
Estorno total online por invoicePOST /api2/creditmemo + invoice_id + refund_type=online
Estorno parcial por pedidoPOST /api2/creditmemo/create + order_increment_id + items[]
Com ajuste de fretePOST /api2/creditmemo + shipping_amount
Com taxa de cancelamentoPOST /api2/creditmemo + adjustment_negative
Com crédito promocionalPOST /api2/creditmemo + adjustment_positive

Recomendações para integração

Recomendado

  • Validar o saldo estornável na invoice antes de chamar — peça GET /api2/invoice?id=... e confira grand_total versus já estornado.
  • Em estornos parciais, usar order_item_id sempre que possível — é mais determinístico que sku.
  • Manter refund_type=offline como padrão da integração; promover para online apenas quando exigido pela política comercial.

Evitar

  • Disparar refund_type=online sem confirmar suporte do método de pagamento — o erro virá do gateway.
  • Criar credit memo esperando reverter em seguida — a operação é irreversível.
  • Misturar mais de um identificador de origem (invoice_id + order_id, por exemplo) no mesmo payload.

Política financeira

Para integrações com sistemas contábeis, registre no comment a referência do lançamento financeiro de origem (NF de devolução, nº do chamado, etc.). Isso facilita a conciliação posterior, já que o credit memo aparece no histórico do pedido e no relatório financeiro.

Erros comuns

StatusExemplo de bodyQuando ocorre
400{"error": "Invalid item"}Item de items sem order_item_id/sku ou com qty não positivo.
400{"error": "Cannot create credit memo"}A invoice ou o pedido não admite mais estorno (já totalmente estornado, cancelado etc.).
400{"error": "Online refund not supported"}refund_type=online em método de pagamento que não suporta estorno online.
401{"error": "Unauthorized"}Authorization ausente ou token expirado.
404{"error": "Invoice not found"}invoice_id ou invoice_increment_id inexistente.
404{"error": "Order not found"}order_id ou order_increment_id inexistente.
409{"error": "Conflict on save"}Duplicidade ou deadlock em gravação concorrente.
500{"error": "Payment gateway error"}Falha repassada pelo método de pagamento durante refund online.

Fora do escopo atual

Itens reconhecidamente ainda não cobertos por esta versão:

  • Listagem (GET /api2/creditmemo) e consulta detalhada (GET /api2/creditmemo?id=...) de credit memos — previstos no roadmap.
API REST da Plataforma Yep · Documentação estática pronta para publicação