> ## Documentation Index
> Fetch the complete documentation index at: https://developers.javalibridge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# beneficiary.status_changed

> O status de um beneficiário mudou.

> [card] [Guia: Beneficiários e instruções de pagamento](https://developers.javalibridge.com/pt-BR/guides/beneficiaries.md)
>
> Regras, status e o que fazer em cada caso.


## OpenAPI

````yaml api-reference/openapi.yaml webhook beneficiary.status_changed
openapi: 3.1.0
info:
  title: Javali Bridge API
  version: 1.22.0
  description: >
    API de pagamentos internacionais do Javali Bridge — v1: USD→BRL
    (fromCurrency/toCurrency), câmbio contratado remessa a remessa (SPOT) e
    pagamento via Pix.


    ## Princípios

    - Cotação e operação são domínios separados. A cotação (`POST
    /v1/fx/quotes`) é apenas preço e não cria remessa. A remessa nasce da
    operação que o cliente quer realizar — na v1, um withdrawal para um
    beneficiário: `POST /v1/fx/quotes` → `POST /v1/remittances/withdrawals`.

    - A cotação é apenas preço: um único preço, igual para PREFUNDED e CREDIT,
    válido para qualquer remetente do cliente. A única tarifa da remessa é o
    spread de câmbio, em percentual. O custo da antecipação (CREDIT) segue o
    contrato e é cobrado no lote de liquidação. Remetente, beneficiário,
    finalidade e funding são informados no withdrawal.

    - USDC Inventory: o cliente pode contratar câmbio antecipadamente. Uma
    cotação com `usage = INVENTORY` é usada uma única vez para criar um
    Inventory Lot (`POST /v1/inventories`), que fixa taxa, volume e vencimento
    da obrigação e gera uma obrigação de valor fixo em USDC. O uso do lote não
    expira; com a obrigação vencida e não paga, o lote fica `SUSPENDED`. O lote
    é consumido depois por withdrawals com `funding.mode = INVENTORY`.

    - Valores monetários são strings decimais. Valores de requisição devem ser
    maiores que zero.

    - Listas usam paginação por cursor (`cursor`, `limit`; resposta com
    `nextCursor`).


    ## Rate limiting

    Respostas 429 trazem `Retry-After` (segundos). Clientes devem respeitar o
    header e aplicar backoff exponencial com jitter.


    ## Erros

    Todo erro retorna `ApiError`. O campo `code` segue o catálogo em
    `components.x-error-catalog`; novos códigos podem ser adicionados sem
    mudança de versão — clientes devem tratar códigos desconhecidos pelo HTTP
    status.


    ## Enums

    Novos valores de status e novos tipos de evento podem ser adicionados sem
    mudança de versão, com a mesma política dos códigos de erro. Clientes devem
    tolerar valores desconhecidos.


    ## Webhooks

    Eventos documentados em `webhooks`. Cada entrega é um `POST` com envelope
    `WebhookEvent` e os headers:

    - `JavaliBridge-Event-Id`: igual a `eventId`; use para deduplicar (entrega é
    at-least-once).

    - `JavaliBridge-Timestamp`: unix epoch (segundos) do envio.

    - `JavaliBridge-Signature`: `v1=<hex(HMAC-SHA256(signingSecret, timestamp +
    "." + rawBody))>`. Rejeite se a assinatura não bater ou se |agora −
    timestamp| > 300s.

    Responda 2xx em até 10s; falhas são reenviadas com backoff exponencial por
    até 24h. A ordem de entrega não é garantida — use `occurredAt` e o estado do
    recurso, ou consulte o recurso via GET.


    ## Chaves de conciliação

    Toda remessa é rastreável pelas mesmas chaves em todos os objetos:

    `externalId` (ID da MSB, único por cliente e imutável) · `quoteId` ·
    `remittanceId` · `settlementId` (CREDIT) · `transactionId` (pagamento Pix) ·
    `inventoryId` (INVENTORY).

    - Quote → `remittanceId`, `externalId` (preenchidos quando a cotação é usada
    por um withdrawal)

    - Remittance → `externalId`, `quoteId` (null em INVENTORY), `inventoryId`
    (INVENTORY), `settlement.settlementId`, `payout.transactionId`

    - Inventory → `quoteId` (cotação que originou o lote), `externalId`;
    remessas do lote em `GET /v1/remittances?inventoryId=`

    - SettlementItem → `remittanceId`, `externalId`, `quoteId`, `transactionId`

    - WalletTransaction → `remittanceId`, `externalId`, `quoteId`,
    `settlementId`

    - Receipt → `remittanceId`, `externalId`, `quoteId`, `transactionId`

    - Webhooks de remessa → snapshot completo da Remittance
servers:
  - url: https://api.javalibridge.example.com
    description: Example production URL - replace before use
  - url: https://sandbox.javalibridge.example.com
    description: Example sandbox URL - replace before use
security:
  - BearerAuth: []
tags:
  - name: Health
  - name: FX Quotes
  - name: Inventories
  - name: Remittances
  - name: Senders
  - name: Beneficiaries
  - name: Credit Line
  - name: Limits
  - name: Wallets
  - name: Settlements
  - name: Webhooks
paths: {}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.