> ## 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. # Convenções da API > Regras que valem para todos os endpoints da API LB Pay Cross-Border Payouts: autenticação, valores, paginação, erros e assinatura de webhooks. ## Autenticação Todos os endpoints exigem um bearer token (`Authorization: Bearer `), exceto `GET /v1/health`. ## 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 você 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 seu. 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: você 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 validade e gera a promessa de pagamento em USDC. O lote é consumido depois por withdrawals com `funding.mode = INVENTORY`. Veja [USDC Inventory](https://developers.javalibridge.com/pt-BR/guides/inventory.md). * Valores monetários são strings decimais. Valores de requisição devem ser maiores que zero. * Listas usam paginação por cursor (`cursor`, `limit`; a resposta traz `nextCursor`). ## Rate limiting Respostas `429` trazem `Retry-After` (segundos). Respeite o header e aplique backoff exponencial com jitter. ## Erros Todo erro retorna `ApiError`. O campo `code` segue o catálogo abaixo. Novos códigos podem ser adicionados sem mudança de versão, então trate códigos desconhecidos pelo status HTTP. | Código | HTTP | Pode repetir | Descrição | | - | - | - | - | | `VALIDATION_ERROR` | 400 | Não | Payload inválido; ver `details` por campo. | | `UNAUTHORIZED` | 401 | Não | Credencial ausente ou inválida. | | `FORBIDDEN` | 403 | Não | Credencial sem permissão para a operação. | | `NOT_FOUND` | 404 | Não | Recurso inexistente na sua conta. | | `IDEMPOTENCY_CONFLICT` | 409 | Não | Mesma `Idempotency-Key` com payload diferente. | | `QUOTE_EXPIRED` | 409 | Não | Cotação expirada; solicite nova cotação. | | `QUOTE_ALREADY_USED` | 409 | Não | Cotação já usada por outra remessa. | | `DUPLICATE_EXTERNAL_ID` | 409 | Não | `externalId` já usado por outra remessa do cliente. | | `AMOUNT_BELOW_MINIMUM` | 422 | Não | Valor abaixo do mínimo por transação (`GET /v1/limits`). | | `AMOUNT_ABOVE_LIMIT` | 422 | Não | Valor acima do máximo por transação (`GET /v1/limits`). | | `FUNDING_MODE_NOT_ENABLED` | 422 | Não | Modalidade de funding não habilitada para o cliente. | | `CREDIT_LIMIT_EXCEEDED` | 422 | Não | Limite de crédito disponível insuficiente. | | `INSUFFICIENT_PREFUNDED_BALANCE` | 422 | Não | Saldo USD pré-fundado nos EUA insuficiente. | | `SENDER_NOT_ELIGIBLE` | 422 | Não | Remetente inexistente, sem nível para transacionar ou com status restritivo. Validado no withdrawal. | | `ACCOUNT_DAILY_LIMIT_EXCEEDED` | 422 | Não | Valor excede o limite diário disponível da conta. | | `SENDER_LIMIT_EXCEEDED` | 422 | Não | Valor excede o limite do remetente na janela (24h/30d/180d). Validado no withdrawal. | | `BENEFICIARY_LIMIT_EXCEEDED` | 422 | Não | Valor excede o limite de recebimento do beneficiário na janela (24h/30d/180d). | | `BENEFICIARY_NOT_ELIGIBLE` | 422 | Não | Beneficiário não está `ACTIVE`. | | `RELATIONSHIP_MISMATCH` | 422 | Não | `senderRelationship` incompatível com o `relationshipType` do beneficiário (`SELF_OWNED` exige `SELF`; `THIRD_PARTY` não aceita `SELF`). | | `PAYMENT_INSTRUCTION_INVALID` | 422 | Não | Instrução de pagamento inexistente, não `APPROVED` ou ambígua. | | `PIX_KEY_NOT_FOUND` | 422 | Não | Chave Pix inexistente no momento do withdrawal. A titularidade é verificada antes do Pix. | | `QUOTE_USAGE_MISMATCH` | 422 | Não | Cotação usada na operação errada (`INVENTORY` em withdrawal ou `REMITTANCE` em `POST /v1/inventories`). | | `DUPLICATE_INVENTORY_EXTERNAL_ID` | 409 | Não | `externalId` já usado por outro Inventory do cliente. | | `INVENTORY_NOT_FOUND` | 422 | Não | Inventory informado no withdrawal não existe na sua conta. Inventory de outro cliente retorna o mesmo erro, sem revelar sua existência. | | `INVENTORY_EXPIRED` | 422 | Não | Inventory fora da validade (`EXPIRED`). | | `INSUFFICIENT_INVENTORY_BALANCE` | 422 | Não | Volume disponível no Inventory informado é menor que `destinationAmount`. Outro lote não é usado automaticamente. | | `RATE_LIMITED` | 429 | Sim | Limite de requisições excedido; respeite `Retry-After`. | | `INTERNAL_ERROR` | 500 | Sim | Erro inesperado; repetir com a mesma `Idempotency-Key`. | | `SERVICE_UNAVAILABLE` | 503 | Sim | Precificação ou processamento temporariamente indisponível, inclusive manutenção (ver `GET /v1/health`). | ## Entrega de webhooks Os eventos estão listados em [Notificações (webhooks)](https://developers.javalibridge.com/pt-BR/guides/webhooks.md). Cada entrega é um `POST` com envelope `WebhookEvent` e estes headers: * `LBPay-Event-Id`: igual a `eventId`. Use para deduplicar; a entrega é at-least-once. * `LBPay-Timestamp`: unix epoch (segundos) do envio. * `LBPay-Signature`: `v1=`. Rejeite a entrega se a assinatura não bater ou se a diferença entre agora e o timestamp for maior que 300 segundos. Responda `2xx` em até 10 segundos. Falhas são reenviadas com backoff exponencial por até 24 horas. 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` (seu ID, único na sua conta e imutável), `quoteId`, `remittanceId`, `settlementId` (`CREDIT`), `transactionId` (pagamento Pix) e `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` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.