> ## Documentation Index > Fetch the complete documentation index at: https://docs.pluggoucash.com/llms.txt > Use this file to discover all available pages before exploring further. # Regras de contrato > Entenda como configurar adquirentes PIX e a diferença entre configuração persistente e override por transação ## Visão geral Contas habilitadas para seleção de adquirente podem escolher até **3 adquirentes PIX** em ordem de prioridade: * **Prioridade 1** — adquirente primária * **Prioridade 2** — adquirente secundária (fallback) * **Prioridade 3** — adquirente terciária (fallback) Existem dois fluxos distintos: | Fluxo | Documentação | Escopo | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | **Definir adquirente geral da conta** | [Atualizar adquirentes](/api-reference/acquirers/update) | Altera o padrão salvo na conta (vale para transações futuras sem override) | | **Override por transação** | [Seleção de adquirente por transação](/api-reference/transactions/guide#seleção-de-adquirente-por-transação) | Escolhe adquirente(s) apenas naquela transação, sem alterar o padrão da conta | Os identificadores de adquirente (`acquirer_key`) devem ser obtidos via [Listar adquirentes](/api-reference/acquirers/list). Não utilize chaves inventadas — apenas adquirentes retornadas pela API estão disponíveis para sua conta. *** ## Pré-requisitos Para utilizar as rotas de adquirentes, sua conta e credencial devem atender aos seguintes requisitos: | Requisito | Descrição | | ----------------------- | ----------------------------------------------------------------------------- | | Permissão da credencial | Tipo **cashin** (apenas entradas) ou **all** (ambas) | | Status da conta | **approved** (aprovada) | | Conta não bloqueada | Sua conta não pode estar bloqueada | | Permissão habilitada | A permissão de `Selecionar adquirentes` da sua conta precisa estar habilitada | *** ## Fluxo recomendado Faça um `GET /pix-cash-in/acquirers` para obter as chaves (`acquirer_key`) disponíveis para sua conta e ver quais já estão configuradas como primária, secundária ou terciária. Use `PUT /pix-cash-in/acquirers` para definir ou atualizar as adquirentes padrão da conta. Essa configuração será usada em todas as transações que **não** informarem override. Ao chamar `POST /transactions`, omita os campos de adquirente para usar o padrão da conta, ou informe `acquirers` para escolher adquirentes apenas naquela transação. Consulte o [guia de transações](/api-reference/transactions/guide#seleção-de-adquirente-por-transação). *** ## Configuração persistente (PUT) As verificações abaixo são aplicadas **na ordem listada**. A primeira falha interrompe o processamento e retorna o erro correspondente. As credenciais `X-Public-Key` e `X-Secret-Key` devem estar presentes nos headers da requisição, além de serem **válidas e ativas**. Se as credenciais estiverem ausentes, inválidas ou inativas, a API retorna `401 Unauthorized`. ```json theme={null} { "error": "Credenciais inválidas", "message": "Chave não encontrada ou inativa" } ``` A credencial utilizada deve possuir permissão do tipo **cashin** (apenas entradas) ou **all** (ambas). Se a credencial não tiver permissão, a API retorna `403 Forbidden`. ```json theme={null} { "success": false, "message": "Esta credencial não tem permissão para realizar esta operação.", "data": null } ``` A conta deve ter a permissão `Selecionar Adquirente` habilitada. Se a permissão não estiver disponível, a API retorna `403 Forbidden`. ```json theme={null} { "success": false, "message": "Seleção de adquirente PIX cash-in não está habilitada para esta conta.", "data": null } ``` Envie um array `acquirers` com até **3 adquirentes**, cada uma com sua prioridade: ```json theme={null} { "acquirers": [ { "acquirer_key": "adq_a", "priority": 1 }, { "acquirer_key": "adq_b", "priority": 2 }, { "acquirer_key": "adq_c", "priority": 3 } ] } ``` Regras de validação: | Regra | Comportamento | | ------------------------------------------ | ---------------------------------------------------------------------- | | `acquirers` | Array obrigatório com 1 a 3 itens | | `acquirer_key` | Obrigatório em cada item; máximo 64 caracteres; formato `^[a-z0-9_]+$` | | `priority` | Obrigatório em cada item; deve ser `1`, `2` ou `3` | | Prioridades duplicadas | Erro `422` | | Mesma adquirente em prioridades diferentes | Erro `422` | | Adquirente indisponível para a conta | Erro `422` imediato (validação estrita) | | Update parcial | Se enviar apenas prioridades 1 e 2, a prioridade 3 é limpa (`null`) | Se houver erros de validação, a API retorna `422 Unprocessable Entity`. ```json theme={null} { "success": false, "message": "Erro de validação", "data": { "errors": { "acquirers": ["Adquirente indisponível para seleção nesta conta."] } } } ``` *** ## Resposta de sucesso (PUT) Se todas as validações passarem, a API retorna `200 OK` com o snapshot das adquirentes ativas: ```json theme={null} { "success": true, "message": "Adquirentes atualizadas com sucesso.", "data": { "active_acquirers": { "primary": { "acquirer_key": "adq_a", "acquirer_name": "Nome A" }, "secondary": { "acquirer_key": "adq_b", "acquirer_name": "Nome B" }, "tertiary": { "acquirer_key": "adq_c", "acquirer_name": "Nome C" } } } } ``` *** ## Diferença entre configuração persistente e override por transação | Aspecto | [Atualizar adquirentes](/api-reference/acquirers/update) | [Seleção por transação](/api-reference/transactions/guide#seleção-de-adquirente-por-transação) | | ----------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Escopo | Altera o padrão da conta | Só na transação atual | | Adquirente indisponível | Erro imediato (`422`) | Ignorada silenciosamente; tenta a próxima | | Persistência | Salva no usuário | Não salva | | Uso típico | Definir fallback padrão | Roteamento pontual por pedido | Use a configuração persistente para definir o comportamento padrão da sua integração. Use o override por transação quando precisar rotear um pedido específico por uma adquirente diferente, sem alterar a configuração global da conta. *** ## Resumo dos códigos de resposta ### GET /pix-cash-in/acquirers | Código | Situação | | ------ | ----------------------------------------------------- | | `200` | Listagem obtida com sucesso | | `401` | Credenciais ausentes, inválidas ou inativas | | `403` | Sem permissão ou seleção de adquirente não habilitada | | `500` | Erro interno do servidor | ### PUT /pix-cash-in/acquirers | Código | Situação | | ------ | ------------------------------------------------------------------------- | | `200` | Adquirentes atualizadas com sucesso | | `401` | Credenciais ausentes, inválidas ou inativas | | `403` | Sem permissão ou seleção de adquirente não habilitada | | `422` | Erro de validação (adquirente indisponível, prioridades duplicadas, etc.) | | `500` | Erro interno do servidor |