Lifecycle

Máquinas de estado do estoque de recebíveis e da operação de antecipação. Os campos e payloads de cada transição estão na Referência Técnica.

Estoque de recebíveis

Um recebível registrado no estoque entra como IN_STOCK e segue:

Status	Significado
IN_STOCK	Disponível para antecipação.
CONSUMED	Antecipado — virou título de uma operação.
EXPIRED	Expirou por TTL (POST /v1/stock/{id}/expire).
CANCELLED	Cancelado (POST /v1/stock/{id}/cancel).

Operação

Uma operação é a antecipação efetiva. Criada via estoque (/v1/stock/request-anticipation) ou diretamente (/v1/operations/direct):

Status	Significado
WAITING_APPROVAL	Aguardando aprovação do Backoffice. Pode ser cancelada.
APPROVED_DIRECT	Dentro do limite de auto-aprovação. Contrato enviado imediatamente.
CONTRACT_SENT / IN_SIGNATURE / SIGNED	Fluxo de assinatura eletrônica do contrato.
WAITING_RELEASE / PROCESSING_PAYMENT	Funding e envio do PIX ao cedente.
PAID	PIX creditado ao cedente.
COMPLETED	Todos os títulos da operação foram pagos pelos sacados.
DENIED / CANCELLED	Negada pelo Backoffice / cancelada pelo originador.

Cancelamento

POST /v1/operations/{id}/cancel só funciona em WAITING_APPROVAL. Após aprovada, retorna 409.

Onde ler o estado: lifecycle_status vs status

As respostas de criação de operação trazem dois campos de estado, ambos declarados como nullable no contrato. A regra é simples:

lifecycle_status é o campo autoritativo. É ele que espelha a coluna persistida da operação (o enum da máquina de estado acima) e o único que aparece nas leituras (GET /v1/operations, GET /v1/operations/{id}). status é um alias legado, emitido por um único endpoint.

Resposta	lifecycle_status	status
POST /v1/stock/request-anticipation	Preenchido — WAITING_APPROVAL ou APPROVED_DIRECT	null (ausente)
POST /v1/operations/direct	null (ausente)	Preenchido — WAITING_APPROVAL ou APPROVED_DIRECT
GET /v1/operations, GET /v1/operations/{id}	Preenchido (nunca nulo)	não existe

Consequências práticas:

• Nunca vêm os dois preenchidos na mesma resposta de criação — cada endpoint emite exatamente um. Leia com precedência: lifecycle_status ?? status.
• As duas portas de criação aplicam o mesmo limite de auto-aprovação da policy: a operação nasce APPROVED_DIRECT quando o total solicitado cabe no auto_approve_limit_brl da policy regente, e WAITING_APPROVAL quando o ultrapassa. Sem limite configurado (ausente ou zero), toda operação nasce WAITING_APPROVAL — a ausência de limite nunca significa "aprova tudo".
• Para acompanhar a operação depois da criação, use GET /v1/operations/{id}, que sempre traz lifecycle_status. status não muda de valor e não deve ser usado como fonte de estado.

Webhooks: lifecycle_status só vem em 2 dos 7 eventos operation.*

A regra lifecycle_status ?? status vale para as respostas HTTP de criação. Ela não se aplica aos webhooks: no payload dos eventos os dois campos podem estar ausentes.

Evento	Traz lifecycle_status?
operation.created	Sim
operation.approved	Sim
operation.contract_signed	Não — operation_id, contract_id, signed_at
operation.paid	Não — operation_id, display_number, opr_liquid_value, payment_sent_at
operation.denied	Não — operation_id, reason
operation.cancelled	Não — operation_id, cancelled_at
operation.overdue	Não — operation_id, overdue_titles_count, total_outstanding_brl

Em 4 desses eventos o estado alcançado é implícito no event_type — cada um corresponde exatamente a uma transição da máquina de estado acima:

Evento	lifecycle_status resultante
operation.contract_signed	SIGNED
operation.paid	PAID
operation.denied	DENIED
operation.cancelled	CANCELLED

operation.overdue não é um estado de operação

Não existe lifecycle_status = OVERDUE — o valor não faz parte do enum, e consultar GET /v1/operations?lifecycle_status=OVERDUE retorna erro. Esse evento reporta títulos vencidos (overdue_titles_count, total_outstanding_brl): quem entra em OVERDUE é o título, não a operação. A operação em si tipicamente segue em PAID — o dinheiro já foi desembolsado ao cedente; quem está inadimplente é o sacado. Acompanhe pelos eventos e pelo status de GET /v1/titles.

Se você precisa do estado explícito da operação ao processar qualquer desses eventos — inclusive os terminais de dinheiro —, faça um GET /v1/operations/{operation_id} com o operation_id do payload. O payload exato de cada evento está em Catálogo de Eventos.